diff --git a/Cargo.lock b/Cargo.lock index ed9155de..10ec141e 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1310,6 +1310,7 @@ dependencies = [ "log", "mdbook-core", "mdbook-html", + "mdbook-markdown", "mdbook-preprocessor", "mdbook-renderer", "mdbook-summary", diff --git a/crates/mdbook-driver/Cargo.toml b/crates/mdbook-driver/Cargo.toml index 1e2e1a6e..5e9b348e 100644 --- a/crates/mdbook-driver/Cargo.toml +++ b/crates/mdbook-driver/Cargo.toml @@ -12,6 +12,7 @@ anyhow.workspace = true log.workspace = true mdbook-core.workspace = true mdbook-html.workspace = true +mdbook-markdown.workspace = true mdbook-preprocessor.workspace = true mdbook-renderer.workspace = true mdbook-summary.workspace = true diff --git a/crates/mdbook-driver/src/lib.rs b/crates/mdbook-driver/src/lib.rs index a8a3d3d5..470fa039 100644 --- a/crates/mdbook-driver/src/lib.rs +++ b/crates/mdbook-driver/src/lib.rs @@ -1,4 +1,62 @@ //! High-level library for running mdBook. +//! +//! This is the high-level library for running +//! [mdBook](https://rust-lang.github.io/mdBook/). There are several +//! reasons for using the programmatic API (over the CLI): +//! +//! - Integrate mdBook in a current project. +//! - Extend the capabilities of mdBook. +//! - Do some processing or test before building your book. +//! - Accessing the public API to help create a new Renderer. +//! +//! ## Additional crates +//! +//! In addition to `mdbook-driver`, there are several other crates available +//! for using and extending mdBook: +//! +//! - [`mdbook_preprocessor`]: Provides support for implementing preprocessors. +//! - [`mdbook_renderer`]: Provides support for implementing renderers. +//! - [`mdbook_markdown`]: The Markdown renderer. +//! - [`mdbook_summary`]: The `SUMMARY.md` parser. +//! - [`mdbook_html`]: The HTML renderer. +//! - [`mdbook_core`]: An internal library that is used by the other crates +//! for shared types. Types from this crate are rexported from the other +//! crates as appropriate. +//! +//! ## Examples +//! +//! If creating a new book from scratch, you'll want to get a [`init::BookBuilder`] via +//! the [`MDBook::init()`] method. +//! +//! ```rust,no_run +//! use mdbook_driver::MDBook; +//! use mdbook_driver::config::Config; +//! +//! let root_dir = "/path/to/book/root"; +//! +//! // create a default config and change a couple things +//! let mut cfg = Config::default(); +//! cfg.book.title = Some("My Book".to_string()); +//! cfg.book.authors.push("Michael-F-Bryan".to_string()); +//! +//! MDBook::init(root_dir) +//! .create_gitignore(true) +//! .with_config(cfg) +//! .build() +//! .expect("Book generation failed"); +//! ``` +//! +//! You can also load an existing book and build it. +//! +//! ```rust,no_run +//! use mdbook_driver::MDBook; +//! +//! let root_dir = "/path/to/book/root"; +//! +//! let mut md = MDBook::load(root_dir) +//! .expect("Unable to load the book"); +//! md.build().expect("Building failed"); +//! ``` pub mod builtin_preprocessors; pub mod builtin_renderers; diff --git a/crates/mdbook-markdown/src/lib.rs b/crates/mdbook-markdown/src/lib.rs index 5b506fa7..a014ca6b 100644 --- a/crates/mdbook-markdown/src/lib.rs +++ b/crates/mdbook-markdown/src/lib.rs @@ -1,4 +1,13 @@ //! Markdown processing used in mdBook. +//! +//! This crate provides functions for processing Markdown in the same way as +//! [mdBook](https://rust-lang.github.io/mdBook/). The [`pulldown_cmark`] +//! crate is used as the underlying parser. This crate re-exports +//! [`pulldown_cmark`] so that you can access its types. +//! +//! The parser in this library adds several modifications to the +//! [`pulldown_cmark`] event stream. For example, it adjusts some links, +//! modifies the behavior of footnotes, and adds various HTML wrappers. use pulldown_cmark::{CodeBlockKind, CowStr, Event, Options, Parser, Tag, TagEnd, html}; use regex::Regex; @@ -8,6 +17,7 @@ use std::fmt::Write; use std::path::Path; use std::sync::LazyLock; +#[doc(inline)] pub use pulldown_cmark; #[cfg(test)] diff --git a/crates/mdbook-preprocessor/src/lib.rs b/crates/mdbook-preprocessor/src/lib.rs index b1d77420..898d19a3 100644 --- a/crates/mdbook-preprocessor/src/lib.rs +++ b/crates/mdbook-preprocessor/src/lib.rs @@ -1,4 +1,9 @@ //! Library to assist implementing an mdbook preprocessor. +//! +//! This library is used to implement a +//! [preprocessor](https://rust-lang.github.io/mdBook/for_developers/preprocessors.html) +//! for [mdBook](https://rust-lang.github.io/mdBook/). See the linked chapter +//! for more information on how to implement a preprocessor. use anyhow::Context; use mdbook_core::book::Book; @@ -17,6 +22,11 @@ pub use mdbook_core::errors; /// An operation which is run immediately after loading a book into memory and /// before it gets rendered. +/// +/// Types that implement the `Preprocessor` trait can be used with +/// [`MDBook::with_preprocessor`] to programmatically add preprocessors. +/// +/// [`MDBook::with_preprocessor`]: https://docs.rs/mdbook-driver/latest/mdbook_driver/struct.MDBook.html#method.with_preprocessor pub trait Preprocessor { /// Get the `Preprocessor`'s name. fn name(&self) -> &str; diff --git a/crates/mdbook-renderer/src/lib.rs b/crates/mdbook-renderer/src/lib.rs index 56365420..12b0aab4 100644 --- a/crates/mdbook-renderer/src/lib.rs +++ b/crates/mdbook-renderer/src/lib.rs @@ -1,4 +1,9 @@ //! Library to assist implementing an mdbook renderer. +//! +//! This library is used to implement a +//! [renderer](https://rust-lang.github.io/mdBook/for_developers/backends.html) +//! for [mdBook](https://rust-lang.github.io/mdBook/). See the linked chapter +//! for more information on how to implement a renderer. use anyhow::Context; use mdbook_core::book::Book; @@ -15,6 +20,11 @@ pub use mdbook_core::config; pub use mdbook_core::errors; /// An mdbook backend. +/// +/// Types that implement the `Renderer` trait can be used with +/// [`MDBook::with_renderer`] to programmatically add renderers. +/// +/// [`MDBook::with_renderer`]: https://docs.rs/mdbook-driver/latest/mdbook_driver/struct.MDBook.html#method.with_renderer pub trait Renderer { /// The `Renderer`'s name. fn name(&self) -> &str; diff --git a/crates/mdbook-summary/src/lib.rs b/crates/mdbook-summary/src/lib.rs index ee1f74b3..f0aad211 100644 --- a/crates/mdbook-summary/src/lib.rs +++ b/crates/mdbook-summary/src/lib.rs @@ -1,4 +1,8 @@ //! Summary parser for mdBook. +//! +//! This is used to parse the +//! [`SUMMARY.md`](https://rust-lang.github.io/mdBook/format/summary.html) +//! file structure for [mdBook](https://rust-lang.github.io/mdBook/). use anyhow::{Context, Error, Result, bail}; use log::{debug, trace, warn}; diff --git a/src/lib.rs b/src/lib.rs deleted file mode 100644 index 122eb565..00000000 --- a/src/lib.rs +++ /dev/null @@ -1,81 +0,0 @@ -//! # mdBook -//! -//! **mdBook** is a tool for rendering a collection of markdown documents into -//! a form more suitable for end users like HTML or EPUB. It offers a command -//! line interface, but this crate can be used if more control is required. -//! -//! This is the API doc, the [user guide] is also available if you want -//! 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 -//! - Accessing the public API to help create a new Renderer -//! - ... -//! -//! > **Note:** While we try to ensure `mdbook`'s command-line interface and -//! > behaviour are backwards compatible, the tool's internals are still -//! > evolving and being iterated on. If you wish to prevent accidental -//! > breakages it is recommended to pin any tools building on top of the -//! > `mdbook` crate to a specific release. -//! -//! # Examples -//! -//! If creating a new book from scratch, you'll want to get a `BookBuilder` via -//! the `MDBook::init()` method. -//! -//! ```rust,no_run -//! use mdbook_driver::MDBook; -//! use mdbook_driver::config::Config; -//! -//! let root_dir = "/path/to/book/root"; -//! -//! // create a default config and change a couple things -//! let mut cfg = Config::default(); -//! cfg.book.title = Some("My Book".to_string()); -//! cfg.book.authors.push("Michael-F-Bryan".to_string()); -//! -//! MDBook::init(root_dir) -//! .create_gitignore(true) -//! .with_config(cfg) -//! .build() -//! .expect("Book generation failed"); -//! ``` -//! -//! You can also load an existing book and build it. -//! -//! ```rust,no_run -//! use mdbook_driver::MDBook; -//! -//! let root_dir = "/path/to/book/root"; -//! -//! let mut md = MDBook::load(root_dir) -//! .expect("Unable to load the book"); -//! md.build().expect("Building failed"); -//! ``` -//! -//! ## Implementing a new Backend -//! -//! `mdbook` has a fairly flexible mechanism for creating additional backends -//! for your book. The general idea is you'll add an extra table in the book's -//! `book.toml` which specifies an executable to be invoked by `mdbook`. This -//! executable will then be called during a build, with an in-memory -//! representation ([`RenderContext`]) of the book being passed to the -//! subprocess via `stdin`. -//! -//! The [`RenderContext`] gives the backend access to the contents of -//! `book.toml` and lets it know which directory all generated artefacts should -//! be placed in. For a much more in-depth explanation, consult the [relevant -//! chapter] in the *For Developers* section of the user guide. -//! -//! To make creating a backend easier, the `mdbook` crate can be imported -//! directly, making deserializing the `RenderContext` easy and giving you -//! access to the various methods for working with the [`Config`]. -//! -//! [user guide]: https://rust-lang.github.io/mdBook/ -//! [`RenderContext`]: mdbook_renderer::RenderContext -//! [relevant chapter]: https://rust-lang.github.io/mdBook/for_developers/backends.html -//! [`Config`]: mdbook_driver::config::Config