actions
/
mdBook
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add documentation for MDBook #30

This commit is contained in:
Mathieu David 2015-08-06 21:10:59 +02:00
parent c6b6069ed3
commit b7214f92a1
4 changed files with 114 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
book-example/src/README.md
View File

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

14
book-example/src/lib/lib.md
View File

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

96
src/book/mdbook.rs
View File

@ -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<Error>> {
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<BookItem>` 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<Error>> {
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<Renderer>) -> Self {
self.renderer = renderer;
self

23
src/lib.rs
View File

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