user0/rust

History

github-actions bfc9951fa8 cargo update Locking 5 packages to latest compatible versions Updating autocfg v1.3.0 -> v1.4.0 Updating flate2 v1.0.33 -> v1.0.34 Updating portable-atomic v1.8.0 -> v1.9.0 Updating syn v2.0.77 -> v2.0.79 Updating tempfile v3.12.0 -> v3.13.0 note: pass `--verbose` to see 81 unchanged dependencies behind latest library dependencies: Locking 0 packages to latest compatible versions note: pass `--verbose` to see 9 unchanged dependencies behind latest rustbook dependencies: Locking 13 packages to latest compatible versions Updating autocfg v1.3.0 -> v1.4.0 Updating cc v1.1.21 -> v1.1.22 Updating flate2 v1.0.33 -> v1.0.34 Updating libc v0.2.158 -> v0.2.159 Updating pkg-config v0.3.30 -> v0.3.31 Updating redox_syscall v0.5.4 -> v0.5.6 Updating serde_spanned v0.6.7 -> v0.6.8 Updating syn v2.0.77 -> v2.0.79 Updating tempfile v3.12.0 -> v3.13.0 Updating thiserror v1.0.63 -> v1.0.64 Updating thiserror-impl v1.0.63 -> v1.0.64 Updating toml_edit v0.22.21 -> v0.22.22 Updating winnow v0.6.18 -> v0.6.20 note: pass `--verbose` to see 30 unchanged dependencies behind latest		2024-09-29 00:22:29 +00:00
..
src	Reformat using the new identifier sorting from rustfmt	2024-09-22 19:11:29 -04:00
Cargo.lock	cargo update	2024-09-29 00:22:29 +00:00
Cargo.toml	Integrate mdbook-spec for the reference.	2024-07-25 17:38:22 -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.