vendor/mdbook/src/lib.rs

   1 //! # mdBook
   2 //!
   3 //! **mdBook** is a tool for rendering a collection of markdown documents into
   4 //! a form more suitable for end users like HTML or EPUB.  It offers a command
   5 //! line interface, but this crate can be used if more control is required.
   6 //!
   7 //! This is the API doc, the [user guide] is also available if you want
   8 //! information about the command line tool, format, structure etc. It is also
   9 //! rendered with mdBook to showcase the features and default theme.
  10 //!
  11 //! Some reasons why you would want to use the crate (over the cli):
  12 //!
  13 //! - Integrate mdbook in a current project
  14 //! - Extend the capabilities of mdBook
  15 //! - Do some processing or test before building your book
  16 //! - Accessing the public API to help create a new Renderer
  17 //! - ...
  18 //!
  19 //! > **Note:** While we try to ensure `mdbook`'s command-line interface and
  20 //! > behaviour are backwards compatible, the tool's internals are still
  21 //! > evolving and being iterated on. If you wish to prevent accidental
  22 //! > breakages it is recommended to pin any tools building on top of the
  23 //! > `mdbook` crate to a specific release.
  24 //!
  25 //! # Examples
  26 //!
  27 //! If creating a new book from scratch, you'll want to get a `BookBuilder` via
  28 //! the `MDBook::init()` method.
  29 //!
  30 //! ```rust,no_run
  31 //! use mdbook::MDBook;
  32 //! use mdbook::config::Config;
  33 //!
  34 //! let root_dir = "/path/to/book/root";
  35 //!
  36 //! // create a default config and change a couple things
  37 //! let mut cfg = Config::default();
  38 //! cfg.book.title = Some("My Book".to_string());
  39 //! cfg.book.authors.push("Michael-F-Bryan".to_string());
  40 //!
  41 //! MDBook::init(root_dir)
  42 //!     .create_gitignore(true)
  43 //!     .with_config(cfg)
  44 //!     .build()
  45 //!     .expect("Book generation failed");
  46 //! ```
  47 //!
  48 //! You can also load an existing book and build it.
  49 //!
  50 //! ```rust,no_run
  51 //! use mdbook::MDBook;
  52 //!
  53 //! let root_dir = "/path/to/book/root";
  54 //!
  55 //! let mut md = MDBook::load(root_dir)
  56 //!     .expect("Unable to load the book");
  57 //! md.build().expect("Building failed");
  58 //! ```
  59 //!
  60 //! ## Implementing a new Backend
  61 //!
  62 //! `mdbook` has a fairly flexible mechanism for creating additional backends
  63 //! for your book. The general idea is you'll add an extra table in the book's
  64 //! `book.toml` which specifies an executable to be invoked by `mdbook`. This
  65 //! executable will then be called during a build, with an in-memory
  66 //! representation ([`RenderContext`]) of the book being passed to the
  67 //! subprocess via `stdin`.
  68 //!
  69 //! The [`RenderContext`] gives the backend access to the contents of
  70 //! `book.toml` and lets it know which directory all generated artefacts should
  71 //! be placed in. For a much more in-depth explanation, consult the [relevant
  72 //! chapter] in the *For Developers* section of the user guide.
  73 //!
  74 //! To make creating a backend easier, the `mdbook` crate can be imported
  75 //! directly, making deserializing the `RenderContext` easy and giving you
  76 //! access to the various methods for working with the [`Config`].
  77 //!
  78 //! [user guide]: https://rust-lang-nursery.github.io/mdBook/
  79 //! [`RenderContext`]: renderer/struct.RenderContext.html
  80 //! [relevant chapter]: https://rust-lang-nursery.github.io/mdBook/for_developers/backends.html
  81 //! [`Config`]: config/struct.Config.html
  82
  83 #![deny(missing_docs)]
  84
  85 #[macro_use]
  86 extern crate error_chain;
  87 extern crate handlebars;
  88 extern crate itertools;
  89 #[macro_use]
  90 extern crate lazy_static;
  91 #[macro_use]
  92 extern crate log;
  93 extern crate memchr;
  94 extern crate pulldown_cmark;
  95 extern crate regex;
  96 extern crate serde;
  97 #[macro_use]
  98 extern crate serde_derive;
  99 #[macro_use]
 100 extern crate serde_json;
 101 extern crate shlex;
 102 extern crate tempfile;
 103 extern crate toml;
 104 extern crate toml_query;
 105
 106 #[cfg(test)]
 107 #[macro_use]
 108 extern crate pretty_assertions;
 109
 110 pub mod book;
 111 pub mod config;
 112 pub mod preprocess;
 113 pub mod renderer;
 114 pub mod theme;
 115 pub mod utils;
 116
 117 /// The current version of `mdbook`.
 118 ///
 119 /// This is provided as a way for custom preprocessors and renderers to do
 120 /// compatibility checks.
 121 pub const MDBOOK_VERSION: &str = env!("CARGO_PKG_VERSION");
 122
 123 pub use book::BookItem;
 124 pub use book::MDBook;
 125 pub use config::Config;
 126 pub use renderer::Renderer;
 127
 128 /// The error types used through out this crate.
 129 pub mod errors {
 130     use std::path::PathBuf;
 131
 132     error_chain!{
 133         foreign_links {
 134             Io(::std::io::Error) #[doc = "A wrapper around `std::io::Error`"];
 135             HandlebarsRender(::handlebars::RenderError) #[doc = "Handlebars rendering failed"];
 136             HandlebarsTemplate(Box<::handlebars::TemplateError>) #[doc = "Unable to parse the template"];
 137             Utf8(::std::string::FromUtf8Error) #[doc = "Invalid UTF-8"];
 138             SerdeJson(::serde_json::Error) #[doc = "JSON conversion failed"];
 139         }
 140
 141         links {
 142             TomlQuery(::toml_query::error::Error, ::toml_query::error::ErrorKind) #[doc = "A TomlQuery error"];
 143         }
 144
 145         errors {
 146             /// A subprocess exited with an unsuccessful return code.
 147             Subprocess(message: String, output: ::std::process::Output) {
 148                 description("A subprocess failed")
 149                 display("{}: {}", message, String::from_utf8_lossy(&output.stdout))
 150             }
 151
 152             /// An error was encountered while parsing the `SUMMARY.md` file.
 153             ParseError(line: usize, col: usize, message: String) {
 154                 description("A SUMMARY.md parsing error")
 155                 display("Error at line {}, column {}: {}", line, col, message)
 156             }
 157
 158             /// The user tried to use a reserved filename.
 159             ReservedFilenameError(filename: PathBuf) {
 160                 description("Reserved Filename")
 161                 display("{} is reserved for internal use", filename.display())
 162             }
 163         }
 164     }
 165
 166     // Box to halve the size of Error
 167     impl From<::handlebars::TemplateError> for Error {
 168         fn from(e: ::handlebars::TemplateError) -> Error {
 169             From::from(Box::new(e))
 170         }
 171     }
 172 }