From b7214f92a1d8f6edfee5cef7079f3450d3cae096 Mon Sep 17 00:00:00 2001 From: Mathieu David Date: Thu, 6 Aug 2015 21:10:59 +0200 Subject: [PATCH] Add documentation for MDBook #30 --- book-example/src/README.md | 2 +- book-example/src/lib/lib.md | 14 +++--- src/book/mdbook.rs | 96 ++++++++++++++++++++++++++++++++++--- src/lib.rs | 23 ++++++--- 4 files changed, 114 insertions(+), 21 deletions(-) diff --git a/book-example/src/README.md b/book-example/src/README.md index 8ccd4de8..80026551 100644 --- a/book-example/src/README.md +++ b/book-example/src/README.md @@ -11,7 +11,7 @@ Issues and feature requests can be posted on the [Github Issue tracker](https:// ## API docs Alongside this book you can also read the [API docs](mdbook/index.html) generated by Rustdoc if you would like -to use mdBook as a crate or write a new parser. +to use mdBook as a crate or write a new renderer. ## License diff --git a/book-example/src/lib/lib.md b/book-example/src/lib/lib.md index 48caed21..a9ec192e 100644 --- a/book-example/src/lib/lib.md +++ b/book-example/src/lib/lib.md @@ -1,7 +1,5 @@ # Rust Library -Check here for the [API docs](../mdbook/index.html) generated by rustdoc. - mdBook is not only a command line tool, it can be used as a crate. You can extend it, integrate it in current projects. Here is a short example: @@ -12,11 +10,13 @@ use mdbook::MDBook; use std::path::Path; fn main() { - let book = MDBook::new(Path::new("my-book")) // Path to root - .set_src(Path::new("src")) // Path from root to source directory - .set_dest(Path::new("book")) // Path from root to output directory - .read_config() // Parse book.json file for configuration + let mut book = MDBook::new(Path::new("my-book")) // Path to root + .set_src(Path::new("src")) // Path from root to source directory + .set_dest(Path::new("book")) // Path from root to output directory + .read_config(); // Parse book.json file for configuration - book.build().unwrap(); // Render the book + book.build().unwrap(); // Render the book } ``` + +Check here for the [API docs](../mdbook/index.html) generated by rustdoc. diff --git a/src/book/mdbook.rs b/src/book/mdbook.rs index ad668b54..4bccc3c3 100644 --- a/src/book/mdbook.rs +++ b/src/book/mdbook.rs @@ -18,10 +18,17 @@ pub struct MDBook { impl MDBook { - pub fn new(path: &Path) -> MDBook { + /// Create a new `MDBook` struct with root directory `root` + /// + /// - The default source directory is set to `root/src` + /// - The default output directory is set to `root/book` + /// + /// They can both be changed by using [`set_src()`](#method.set_src) and [`set_dest()`](#method.set_dest) + + pub fn new(root: &Path) -> MDBook { // Hacky way to check if the path exists... Until PathExt moves to stable - match metadata(path) { + match metadata(root) { Err(_) => panic!("Directory does not exist"), Ok(f) => { if !f.is_dir() { @@ -31,16 +38,39 @@ impl MDBook { } MDBook { - root: path.to_path_buf(), + root: root.to_path_buf(), content: vec![], config: BookConfig::new() - .set_src(&path.join("src")) - .set_dest(&path.join("book")) + .set_src(&root.join("src")) + .set_dest(&root.join("book")) .to_owned(), renderer: Box::new(HtmlHandlebars::new()), } } + /// Returns a flat depth-first iterator over the elements of the book in the form of a tuple: + /// `(section: String, bookitem: &BookItem)` + /// + /// ```no_run + /// # extern crate mdbook; + /// # use mdbook::MDBook; + /// # use std::path::Path; + /// # fn main() { + /// # let mut book = MDBook::new(Path::new("mybook")); + /// for (section, element) in book.iter() { + /// println!("{} {}", section, element.name); + /// } + /// + /// // would print something like this: + /// // 1. Chapter 1 + /// // 1.1 Sub Chapter + /// // 1.2 Sub Chapter + /// // 2. Chapter 2 + /// // + /// // etc. + /// # } + /// ``` + pub fn iter(&self) -> BookItems { BookItems { items: &self.content[..], @@ -49,6 +79,19 @@ impl MDBook { } } + /// `init()` creates some boilerplate files and directories to get you started with your book. + /// + /// ```text + /// book-test/ + /// ├── book + /// └── src + /// ├── chapter_1.md + /// └── SUMMARY.md + /// ``` + /// + /// It uses the paths given as source and output directories and adds a `SUMMARY.md` and a + /// `chapter_1.md` to the source directory. + pub fn init(&self) -> Result<(), Box> { debug!("[fn]: init"); @@ -106,6 +149,12 @@ impl MDBook { return Ok(()); } + /// The `build()` method is the one where everything happens. First it parses `SUMMARY.md` to + /// construct the book's structure in the form of a `Vec` and then calls `render()` + /// method of the current renderer. + /// + /// It is the renderer who generates all the output files. + pub fn build(&mut self) -> Result<(), Box> { debug!("[fn]: build"); @@ -120,12 +169,47 @@ impl MDBook { } - // Builder functions + /// Parses the `book.json` file (if it exists) to extract the configuration parameters. + /// The `book.json` file should be in the root directory of the book. + /// The root directory is the one specified when creating a new `MDBook` + /// + /// ```no_run + /// # extern crate mdbook; + /// # use mdbook::MDBook; + /// # use std::path::Path; + /// # fn main() { + /// let mut book = MDBook::new(Path::new("root_dir")); + /// # } + /// ``` + /// + /// In this example, `root_dir` will be the root directory of our book and is specified in function + /// of the current working directory by using a relative path instead of an absolute path. + pub fn read_config(mut self) -> Self { self.config.read_config(&self.root); self } + /// You can change the default renderer to another one by using this method. The only requirement + /// is for your renderer to implement the [Renderer trait](../../renderer/renderer/trait.Renderer.html) + /// + /// ```no_run + /// extern crate mdbook; + /// use mdbook::MDBook; + /// use mdbook::renderer::HtmlHandlebars; + /// # use std::path::Path; + /// + /// fn main() { + /// let mut book = MDBook::new(Path::new("mybook")) + /// .set_renderer(Box::new(HtmlHandlebars::new())); + /// + /// // In this example we replace the default renderer by the default renderer... + /// // Don't forget to put your renderer in a Box + /// } + /// ``` + /// + /// **note:** Don't forget to put your renderer in a `Box` before passing it to `set_renderer()` + pub fn set_renderer(mut self, renderer: Box) -> Self { self.renderer = renderer; self diff --git a/src/lib.rs b/src/lib.rs index 6d1222ea..504b0af2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -24,13 +24,12 @@ //! use std::path::Path; //! //! fn main() { -//! let mut book = MDBook::new(Path::new("book-test")) // ERROR directory does not exist... -//! .set_src(Path::new("source")) -//! .set_dest(Path::new("output")) -//! .read_config(); // Reads book.json file for settings +//! let mut book = MDBook::new(Path::new("my-book")) // Path to root +//! .set_src(Path::new("src")) // Path from root to source directory +//! .set_dest(Path::new("book")) // Path from root to output directory +//! .read_config(); // Parse book.json file for configuration //! -//! book.init().unwrap(); -//! book.build().unwrap(); +//! book.build().unwrap(); // Render the book //! } //! ``` //! @@ -58,7 +57,17 @@ //! 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 +//! +//! ```ignore +//! utils::path::create_path(path: &Path) +//! ``` +//! This function creates all the directories in a given path if they do not exist +//! +//! Make sure to take a look at it. #[macro_use] pub mod macros;