Fixed a couple issues with the docs

src/book/init.rs

@@ -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(())
     }
 

src/book/summary.rs

@@ -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 {

src/lib.rs

@@ -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;