2015-08-06 18:38:48 +08:00
//! # mdBook
//!
//! **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.
//!
//! Some reasons why you would want to use the crate (over the cli):
//!
//! - Integrate mdbook in a current project
//! - Extend the capabilities of mdBook
//! - Do some processing or test before building your book
//! - Write a new Renderer
//! - ...
//!
//! ## Example
//!
2015-08-06 21:04:27 +08:00
//! ```no_run
2015-08-06 18:38:48 +08:00
//! extern crate mdbook;
//!
//! use mdbook::MDBook;
//!
2017-06-06 17:58:08 +08:00
//! # #[allow(unused_variables)]
2015-08-06 18:38:48 +08:00
//! fn main() {
2017-06-06 17:58:08 +08:00
//! let mut book = MDBook::new("my-book") // Path to root
//! .with_source("src") // Path from root to source directory
//! .with_destination("book") // Path from root to output directory
//! .read_config() // Parse book.toml configuration file
2017-06-23 07:10:18 +08:00
//! .expect("I don't handle configuration file errors, but you should!");
2015-08-06 18:38:48 +08:00
//!
2017-06-06 17:58:08 +08:00
//! book.build().unwrap(); // Render the book
2015-08-06 18:38:48 +08:00
//! }
//! ```
//!
//! ## 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)
//!
//! And then you can swap in your renderer like this:
//!
2015-08-06 21:04:27 +08:00
//! ```no_run
//! # extern crate mdbook;
//! #
//! # use mdbook::MDBook;
//! # use mdbook::renderer::HtmlHandlebars;
//! #
2017-06-06 17:58:08 +08:00
//! # #[allow(unused_variables)]
2015-08-06 21:04:27 +08:00
//! # fn main() {
//! # let your_renderer = HtmlHandlebars::new();
//! #
2017-06-06 17:58:08 +08:00
//! let book = MDBook::new("my-book").set_renderer(Box::new(your_renderer));
2015-08-06 21:04:27 +08:00
//! # }
2015-08-06 18:38:48 +08:00
//! ```
2015-08-06 21:04:27 +08:00
//! 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.
2015-08-07 03:10:59 +08:00
//!
//! ## utils
//!
2017-06-06 17:58:08 +08:00
//! 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)
2015-08-07 03:10:59 +08:00
//!
2017-06-06 17:58:08 +08:00
//! 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.
2015-08-07 03:10:59 +08:00
//!
//! Make sure to take a look at it.
2015-08-06 18:38:48 +08:00
2017-06-24 23:48:50 +08:00
#[ macro_use ]
extern crate error_chain ;
2017-02-16 11:34:37 +08:00
#[ macro_use ]
2017-05-19 01:32:08 +08:00
extern crate serde_derive ;
extern crate serde ;
2017-06-24 23:48:50 +08:00
#[ macro_use ]
extern crate serde_json ;
2017-05-19 01:32:08 +08:00
2016-03-28 00:22:17 +08:00
extern crate handlebars ;
extern crate pulldown_cmark ;
2017-02-16 14:39:13 +08:00
extern crate regex ;
2016-03-28 00:22:17 +08:00
2017-05-19 19:04:37 +08:00
#[ macro_use ]
extern crate log ;
2015-08-06 18:38:48 +08:00
pub mod book ;
2017-05-19 01:32:08 +08:00
pub mod config ;
2015-07-18 06:04:20 +08:00
mod parse ;
2015-07-19 06:08:38 +08:00
pub mod renderer ;
pub mod theme ;
2015-07-30 21:20:55 +08:00
pub mod utils ;
2015-07-07 08:56:19 +08:00
2015-07-19 06:08:38 +08:00
pub use book ::MDBook ;
pub use book ::BookItem ;
2015-08-06 04:35:26 +08:00
pub use renderer ::Renderer ;
2017-06-24 23:48:50 +08:00
/// The error types used through out this crate.
pub mod errors {
error_chain! {
foreign_links {
Io ( ::std ::io ::Error ) ;
2017-06-25 00:10:06 +08:00
HandlebarsRender ( ::handlebars ::RenderError ) ;
HandlebarsTemplate ( ::handlebars ::TemplateError ) ;
Utf8 ( ::std ::string ::FromUtf8Error ) ;
2017-06-24 23:48:50 +08:00
}
2017-06-25 00:04:57 +08:00
errors {
Subprocess ( message : String , output : ::std ::process ::Output ) {
description ( " A subprocess failed " )
}
}
2017-06-24 23:48:50 +08:00
}
}