user0/rust

History

bors c8f9423028 Auto merge of #139727 - rust-lang:cargo_update, r=Mark-Simulacrum Weekly `cargo update` Automation to keep dependencies in `Cargo.lock` current. The following is the output from `cargo update`: ```txt compiler & tools dependencies: Locking 11 packages to latest compatible versions Updating bstr v1.11.3 -> v1.12.0 Updating clap v4.5.35 -> v4.5.36 Updating clap_builder v4.5.35 -> v4.5.36 Updating crossbeam-channel v0.5.14 -> v0.5.15 Updating jiff v0.2.5 -> v0.2.6 Updating jiff-static v0.2.5 -> v0.2.6 Updating jsonpath-rust v1.0.0 -> v1.0.1 Updating linux-raw-sys v0.9.3 -> v0.9.4 Updating miniz_oxide v0.8.7 -> v0.8.8 Updating self_cell v1.1.0 -> v1.2.0 Updating winnow v0.7.4 -> v0.7.6 note: pass `--verbose` to see 38 unchanged dependencies behind latest library dependencies: Locking 1 package to latest compatible version Updating miniz_oxide v0.8.7 -> v0.8.8 note: pass `--verbose` to see 4 unchanged dependencies behind latest rustbook dependencies: Locking 9 packages to latest compatible versions Updating bstr v1.11.3 -> v1.12.0 Updating cc v1.2.18 -> v1.2.19 Updating clap v4.5.35 -> v4.5.36 Updating clap_builder v4.5.35 -> v4.5.36 Updating jiff v0.2.5 -> v0.2.6 Updating jiff-static v0.2.5 -> v0.2.6 Updating linux-raw-sys v0.9.3 -> v0.9.4 Updating miniz_oxide v0.8.7 -> v0.8.8 Updating winnow v0.7.4 -> v0.7.6 ```		2025-04-21 12:07:02 +00:00
..
src	Update mdbook to 0.4.47	2025-03-12 06:11:38 -07:00
.gitignore	Update mdbook to 0.4.42	2024-11-08 15:38:32 -08:00
Cargo.lock	Auto merge of #139727 - rust-lang:cargo_update, r=Mark-Simulacrum	2025-04-21 12:07:02 +00:00
Cargo.toml	Update mdbook to 0.4.48	2025-04-01 06:51:47 -07:00
README.md	Add a README to rustbook to explain its purpose	2024-07-27 08:54:04 -07:00

README.md

Rustbook

This is a wrapper around mdbook, which is used to generate the book-style documentation in the Rust project. This wrapper serves a few purposes:

Avoids some of mdbook's large, optional dependencies (like tokio, webserver, etc.).
Makes it a little easier to customize and override some of mdbook's behaviors (like swapping in custom preprocessors).
Supports vendoring of the source via Rust's normal release process.

This is invoked automatically when building mdbook-style documentation, for example via ./x doc.

Cargo workspace

This package defines a separate cargo workspace from the main Rust workspace for a few reasons (ref #127786:

Avoids requiring checking out submodules for developers who are not working on the documentation. Otherwise, some submodules such as those that have custom preprocessors would be required for cargo to find the dependencies.
Avoids problems with updating dependencies. Unfortunately this workspace has a rather large set of dependencies, which can make coordinating updates difficult (see #127890).

Custom preprocessors

Some books have custom mdbook preprocessors that need to be integrated with both the book's repository, and the build system here in the rust-lang/rust repository. To add a new preprocessor, there are few things to do:

Implement the preprocessor as a cargo library in the book's repository.
Add the [preprocessor] table to the book's book.toml file. I recommend setting the command so that the preprocessor gets built automatically. It may look something like:

[preprocessor.spec]
command = "cargo run --manifest-path my-cool-extension/Cargo.toml"

[build]
extra-watch-dirs = ["my-cool-extension/src"]

Add the preprocessor as a dependency in rustbook's Cargo.toml.
Call with_preprocessor in rustbook/src/main.rs.
Be sure to test that it generates correctly, such as running ./x doc MY-BOOK-NAME --open and verify the content looks correct.
Also test tidy and your book, such as running ./x test tidy and ./x test MY-BOOK-NAME.