src/vendor/mdbook/src/lib.rs

   1 //! # mdBook
   2 //!
   3 //! **mdBook** is similar to Gitbook but implemented in Rust.
   4 //! It offers a command line interface, but can also be used as a regular crate.
   5 //!
   6 //! This is the API doc, but you can find a [less "low-level" documentation here](../index.html) that
   7 //! contains information about the command line tool, format, structure etc.
   8 //! It is also rendered with mdBook to showcase the features and default theme.
   9 //!
  10 //! Some reasons why you would want to use the crate (over the cli):
  11 //!
  12 //! - Integrate mdbook in a current project
  13 //! - Extend the capabilities of mdBook
  14 //! - Do some processing or test before building your book
  15 //! - Write a new Renderer
  16 //! - ...
  17 //!
  18 //! ## Example
  19 //!
  20 //! ```no_run
  21 //! extern crate mdbook;
  22 //!
  23 //! use mdbook::MDBook;
  24 //! use std::path::Path;
  25 //!
  26 //! fn main() {
  27 //!     let mut book =  MDBook::new(Path::new("my-book"))   // Path to root
  28 //!                         .set_src(Path::new("src"))      // Path from root to source directory
  29 //!                         .set_dest(Path::new("book"))    // Path from root to output directory
  30 //!                         .read_config();                 // Parse book.json file for configuration
  31 //!
  32 //!     book.build().unwrap();                              // Render the book
  33 //! }
  34 //! ```
  35 //!
  36 //! ## Implementing a new Renderer
  37 //!
  38 //! If you want to create a new renderer for mdBook, the only thing you have to do is to implement
  39 //! the [Renderer trait](renderer/renderer/trait.Renderer.html)
  40 //!
  41 //! And then you can swap in your renderer like this:
  42 //!
  43 //! ```no_run
  44 //! # extern crate mdbook;
  45 //! #
  46 //! # use mdbook::MDBook;
  47 //! # use mdbook::renderer::HtmlHandlebars;
  48 //! # use std::path::Path;
  49 //! #
  50 //! # fn main() {
  51 //! #   let your_renderer = HtmlHandlebars::new();
  52 //! #
  53 //!     let book =  MDBook::new(Path::new("my-book")).set_renderer(Box::new(your_renderer));
  54 //! # }
  55 //! ```
  56 //! If you make a renderer, you get the book constructed in form of `Vec<BookItems>` and you get
  57 //! the book config in a `BookConfig` struct.
  58 //!
  59 //! It's your responsability to create the necessary files in the correct directories.
  60 //!
  61 //! ## utils
  62 //!
  63 //! I have regrouped some useful functions in the [utils](utils/index.html) module, like the following function
  64 //!
  65 //! ```ignore
  66 //! utils::fs::create_path(path: &Path)
  67 //! ```
  68 //! This function creates all the directories in a given path if they do not exist
  69 //!
  70 //! Make sure to take a look at it.
  71
  72 extern crate serde;
  73 #[macro_use]
  74 extern crate serde_json;
  75 extern crate handlebars;
  76 extern crate pulldown_cmark;
  77 extern crate regex;
  78
  79 #[macro_use] extern crate log;
  80 pub mod book;
  81 mod parse;
  82 pub mod renderer;
  83 pub mod theme;
  84 pub mod utils;
  85
  86 pub use book::MDBook;
  87 pub use book::BookItem;
  88 pub use book::BookConfig;
  89 pub use renderer::Renderer;