Update crate docs

This updates the crate-level docs to add a little more detail for each
crate.

This also drops the `mdbook` library crate, as it is no longer needed.

Author: ehuss

Cargo.lock

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

crates/mdbook-driver/Cargo.toml

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

crates/mdbook-driver/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)]

crates/mdbook-markdown/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;

crates/mdbook-preprocessor/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;

crates/mdbook-renderer/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};