Fixed a couple issues with the docs

This commit is contained in:
Michael Bryan 2017-12-11 18:50:31 +11:00
parent 5041359817
commit 75dac15f09
No known key found for this signature in database
GPG Key ID: E9C602B0D9A998DC
3 changed files with 30 additions and 19 deletions

View File

@ -61,7 +61,7 @@ impl BookBuilder {
/// - Create a `.gitignore` (if applicable)
/// - Create a themes directory and populate it (if applicable)
/// - Generate a `book.toml` file,
/// - Then load the book so we can
/// - Then load the book so we can build it or run tests.
pub fn build(&self) -> Result<MDBook> {
info!("Creating a new book with stub content");
@ -146,6 +146,10 @@ impl BookBuilder {
fn build_gitignore(&self) -> Result<()> {
debug!("[*]: Creating .gitignore");
let mut f = File::create(self.root.join(".gitignore"))?;
writeln!(f, "{}", self.config.build.build_dir.display())?;
Ok(())
}

View File

@ -13,8 +13,8 @@ use errors::*;
/// # Summary Format
///
/// **Title:** It's common practice to begin with a title, generally
/// "# Summary". But it is not mandatory, the parser just ignores it. So you
/// can too if you feel like it.
/// "# Summary". It's not mandatory and the parser (currently) ignores it, so
/// you can too if you feel like it.
///
/// **Prefix Chapter:** Before the main numbered chapters you can add a couple
/// of elements that will not be numbered. This is useful for forewords,
@ -35,7 +35,8 @@ use errors::*;
/// - [Title of the Chapter](relative/path/to/markdown.md)
/// ```
///
/// You can either use - or * to indicate a numbered chapter.
/// You can either use - or * to indicate a numbered chapter, the parser doesn't
/// care but you'll probably want to stay consistent.
///
/// **Suffix Chapter:** After the numbered chapters you can add a couple of
/// non-numbered chapters. They are the same as prefix chapters but come after
@ -125,7 +126,7 @@ impl From<Link> for SummaryItem {
}
}
/// A recursive descent parser for a `SUMMARY.md`.
/// A recursive descent (-ish) parser for a `SUMMARY.md`.
///
///
/// # Grammar
@ -203,6 +204,8 @@ impl<'a> SummaryParser<'a> {
}
}
/// Get the current line and column to give the user more useful error
/// messages.
fn current_location(&self) -> (usize, usize) {
let byte_offset = self.stream.get_offset();
@ -459,7 +462,6 @@ fn get_last_link(links: &mut [SummaryItem]) -> Result<(usize, &mut Link)> {
})
}
/// Removes the styling from a list of Markdown events and returns just the
/// plain text.
fn stringify_events(events: Vec<Event>) -> String {
@ -712,4 +714,4 @@ mod tests {
assert_eq!(got, should_be);
}
}
}

View File

@ -1,11 +1,11 @@
//! # mdBook
//!
//! **mdBook** is similar to Gitbook but implemented in Rust.
//! **mdBook** is similar to GitBook but implemented in Rust.
//! It offers a command line interface, but can also be used as a regular crate.
//!
//! This is the API doc, but you can find a [less "low-level" documentation here](../index.html)
//! that contains information about the command line tool, format, structure etc.
//! It is also rendered with mdBook to showcase the features and default theme.
//! This is the API doc, the [user guide] is also available if you want
//! information about the command line tool, format, structure etc. It is also
//! rendered with mdBook to showcase the features and default theme.
//!
//! Some reasons why you would want to use the crate (over the cli):
//!
@ -52,8 +52,9 @@
//!
//! ## Implementing a new Renderer
//!
//! If you want to create a new renderer for mdBook, the only thing you have to do is to implement
//! the [Renderer trait](renderer/renderer/trait.Renderer.html)
//! If you want to create a new renderer for mdBook, the only thing you have to
//! do is to implement the [Renderer](renderer/renderer/trait.Renderer.html)
//! trait.
//!
//! And then you can swap in your renderer like this:
//!
@ -71,22 +72,26 @@
//! book.set_renderer(your_renderer);
//! # }
//! ```
//! If you make a renderer, you get the book constructed in form of `Vec<BookItems>` and you get
//! the book config in a `BookConfig` struct.
//!
//! It's your responsability to create the necessary files in the correct directories.
//! If you make a renderer, you get the book constructed in form of
//! `Vec<BookItems>` and you get ! the book config in a `BookConfig` struct.
//!
//! It's your responsability to create the necessary files in the correct
//! directories.
//!
//! ## utils
//!
//! I have regrouped some useful functions in the [utils](utils/index.html) module, like the
//! following function [`utils::fs::create_file(path:
//! &Path)`](utils/fs/fn.create_file.html)
//! I have regrouped some useful functions in the [utils](utils/index.html)
//! module, like the following function [`utils::fs::create_file(path:
//! &Path)`](utils/fs/fn.create_file.html).
//!
//! This function creates a file and returns it. But before creating the file
//! it checks every directory in the path to see if it exists, and if it does
//! not it will be created.
//!
//! Make sure to take a look at it.
//!
//! [user guide]: https://rust-lang-nursery.github.io/mdBook/
#[macro_use]
extern crate error_chain;