Merge pull request rust-lang#1171 from mark-i-m/master

implement support for book parts

Author: ehuss

book-example/src/format/summary.md

@@ -22,15 +22,27 @@ allow for easy parsing. Let's see how you should format your `SUMMARY.md` file.
    [Title of prefix element](relative/path/to/markdown.md)
    ```
 
-3. ***Numbered Chapter*** Numbered chapters are the main content of the book,
+3. ***Part Title:*** Headers can be used as a title for the following numbered
+   chapters. This can be used to logically separate different sections
+   of book. The title is rendered as unclickable text.
+   Titles are optional, and the numbered chapters can be broken into as many
+   parts as desired.
+
+4. ***Numbered Chapter*** Numbered chapters are the main content of the book,
    they will be numbered and can be nested, resulting in a nice hierarchy
    (chapters, sub-chapters, etc.)
    ```markdown
+   # Title of Part
+
    - [Title of the Chapter](relative/path/to/markdown.md)
+
+   # Title of Another Part
+
+   - [More Chapters](relative/path/to/markdown2.md)
    ```
    You can either use `-` or `*` to indicate a numbered chapter.
 
-4. ***Suffix Chapter*** After the numbered chapters you can add a couple of
+5. ***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
    the numbered chapters instead of before.
 
@@ -50,5 +62,5 @@ error.
   of contents, as you can see for the next chapter in the table of contents on the left.
   Draft chapters are written like normal chapters but without writing the path to the file
   ```markdown
-  - [Draft chapter]()  
-  ``` 
+  - [Draft chapter]()
+  ```

src/book/book.rs

@@ -133,6 +133,8 @@ pub enum BookItem {
     Chapter(Chapter),
     /// A section separator.
     Separator,
+    /// A part title.
+    PartTitle(String),
 }
 
 impl From<Chapter> for BookItem {
@@ -229,11 +231,12 @@ fn load_summary_item<P: AsRef<Path> + Clone>(
     src_dir: P,
     parent_names: Vec<String>,
 ) -> Result<BookItem> {
-    match *item {
+    match item {
         SummaryItem::Separator => Ok(BookItem::Separator),
         SummaryItem::Link(ref link) => {
             load_chapter(link, src_dir, parent_names).map(BookItem::Chapter)
         }
+        SummaryItem::PartTitle(title) => Ok(BookItem::PartTitle(title.clone())),
     }
 }
 
@@ -569,6 +572,7 @@ And here is some \
                 location: Some(PathBuf::from("")),
                 ..Default::default()
             })],
+
             ..Default::default()
         };
 

src/book/mod.rs

@@ -132,6 +132,7 @@ impl MDBook {
     ///     match *item {
     ///         BookItem::Chapter(ref chapter) => {},
     ///         BookItem::Separator => {},
+    ///         BookItem::PartTitle(ref title) => {}
     ///     }
     /// }
     ///