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

View File

@ -13,8 +13,8 @@ use errors::*;
/// # Summary Format /// # Summary Format
/// ///
/// **Title:** It's common practice to begin with a title, generally /// **Title:** It's common practice to begin with a title, generally
/// "# Summary". But it is not mandatory, the parser just ignores it. So you /// "# Summary". It's not mandatory and the parser (currently) ignores it, so
/// can too if you feel like it. /// you can too if you feel like it.
/// ///
/// **Prefix Chapter:** Before the main numbered chapters you can add a couple /// **Prefix Chapter:** Before the main numbered chapters you can add a couple
/// of elements that will not be numbered. This is useful for forewords, /// 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) /// - [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 /// **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 /// 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 /// # 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) { fn current_location(&self) -> (usize, usize) {
let byte_offset = self.stream.get_offset(); 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 /// Removes the styling from a list of Markdown events and returns just the
/// plain text. /// plain text.
fn stringify_events(events: Vec<Event>) -> String { fn stringify_events(events: Vec<Event>) -> String {
@ -712,4 +714,4 @@ mod tests {
assert_eq!(got, should_be); assert_eq!(got, should_be);
} }
} }

View File

@ -1,11 +1,11 @@
//! # mdBook //! # 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. //! 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) //! This is the API doc, the [user guide] is also available if you want
//! that contains information about the command line tool, format, structure etc. //! information about the command line tool, format, structure etc. It is also
//! It is also rendered with mdBook to showcase the features and default theme. //! rendered with mdBook to showcase the features and default theme.
//! //!
//! Some reasons why you would want to use the crate (over the cli): //! Some reasons why you would want to use the crate (over the cli):
//! //!
@ -52,8 +52,9 @@
//! //!
//! ## Implementing a new Renderer //! ## Implementing a new Renderer
//! //!
//! If you want to create a new renderer for mdBook, the only thing you have to do is to implement //! If you want to create a new renderer for mdBook, the only thing you have to
//! the [Renderer trait](renderer/renderer/trait.Renderer.html) //! do is to implement the [Renderer](renderer/renderer/trait.Renderer.html)
//! trait.
//! //!
//! And then you can swap in your renderer like this: //! And then you can swap in your renderer like this:
//! //!
@ -71,22 +72,26 @@
//! book.set_renderer(your_renderer); //! 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 //! ## utils
//! //!
//! I have regrouped some useful functions in the [utils](utils/index.html) module, like the //! I have regrouped some useful functions in the [utils](utils/index.html)
//! following function [`utils::fs::create_file(path: //! module, like the following function [`utils::fs::create_file(path:
//! &Path)`](utils/fs/fn.create_file.html) //! &Path)`](utils/fs/fn.create_file.html).
//! //!
//! This function creates a file and returns it. But before creating the file //! 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 //! it checks every directory in the path to see if it exists, and if it does
//! not it will be created. //! not it will be created.
//! //!
//! Make sure to take a look at it. //! Make sure to take a look at it.
//!
//! [user guide]: https://rust-lang-nursery.github.io/mdBook/
#[macro_use] #[macro_use]
extern crate error_chain; extern crate error_chain;