user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
rust/src/tools/rustbook
History
github-actions acbc79c8da cargo update 
compiler & tools dependencies:
     Locking 40 packages to latest compatible versions
    Updating clap v4.5.37 -> v4.5.38
    Updating clap_builder v4.5.37 -> v4.5.38
    Updating ctrlc v3.4.6 -> v3.4.7
    Updating derive_setters v0.1.6 -> v0.1.7
    Updating getrandom v0.3.2 -> v0.3.3
    Updating icu_collections v1.5.0 -> v2.0.0
      Adding icu_locale_core v2.0.0
    Updating icu_normalizer v1.5.0 -> v2.0.0
    Updating icu_normalizer_data v1.5.1 -> v2.0.0
    Updating icu_properties v1.5.1 -> v2.0.0
    Updating icu_properties_data v1.5.1 -> v2.0.0
      Adding icu_provider v2.0.0
    Updating idna_adapter v1.2.0 -> v1.2.1
    Updating jiff v0.2.12 -> v0.2.13
    Updating jiff-static v0.2.12 -> v0.2.13
    Updating libffi v4.0.0 -> v4.1.0
    Updating libffi-sys v3.2.0 -> v3.3.1
    Updating libloading v0.8.6 -> v0.8.7
    Updating libm v0.2.13 -> v0.2.15
      Adding litemap v0.8.0
    Updating nix v0.29.0 -> v0.30.1
      Adding potential_utf v0.1.2
    Updating rustc-build-sysroot v0.5.4 -> v0.5.5
      Adding tinystr v0.8.1
    Updating tokio v1.44.2 -> v1.45.0
    Updating unic-langid v0.9.5 -> v0.9.6
    Updating unic-langid-impl v0.9.5 -> v0.9.6
    Updating unic-langid-macros v0.9.5 -> v0.9.6
    Updating unic-langid-macros-impl v0.9.5 -> v0.9.6
    Removing utf16_iter v1.0.5
      Adding wasm-encoder v0.230.0
      Adding wasmparser v0.230.0
    Updating wast v229.0.0 -> v230.0.0
    Updating wat v1.229.0 -> v1.230.0
    Updating winnow v0.7.9 -> v0.7.10
    Removing write16 v1.0.0
      Adding writeable v0.6.1
      Adding yoke v0.8.0
      Adding yoke-derive v0.8.0
      Adding zerotrie v0.2.2
      Adding zerovec v0.11.2
      Adding zerovec-derive v0.11.1
note: pass `--verbose` to see 36 unchanged dependencies behind latest

library dependencies:
     Locking 0 packages to latest compatible versions
note: pass `--verbose` to see 3 unchanged dependencies behind latest

rustbook dependencies:
     Locking 26 packages to latest compatible versions
    Updating cc v1.2.21 -> v1.2.22
    Updating clap v4.5.37 -> v4.5.38
    Updating clap_builder v4.5.37 -> v4.5.38
    Updating clap_complete v4.5.48 -> v4.5.50
    Updating getrandom v0.3.2 -> v0.3.3
    Updating icu_collections v1.5.0 -> v2.0.0
      Adding icu_locale_core v2.0.0
    Removing icu_locid v1.5.0
    Removing icu_locid_transform v1.5.0
    Removing icu_locid_transform_data v1.5.1
    Updating icu_normalizer v1.5.0 -> v2.0.0
    Updating icu_normalizer_data v1.5.1 -> v2.0.0
    Updating icu_properties v1.5.1 -> v2.0.0
    Updating icu_properties_data v1.5.1 -> v2.0.0
    Updating icu_provider v1.5.0 -> v2.0.0
    Removing icu_provider_macros v1.5.0
    Updating idna_adapter v1.2.0 -> v1.2.1
    Updating jiff v0.2.12 -> v0.2.13
    Updating jiff-static v0.2.12 -> v0.2.13
    Updating litemap v0.7.5 -> v0.8.0
      Adding potential_utf v0.1.2
    Updating tinystr v0.7.6 -> v0.8.1
    Removing utf16_iter v1.0.5
    Updating web_atoms v0.1.1 -> v0.1.2
    Updating winnow v0.7.9 -> v0.7.10
    Removing write16 v1.0.0
    Updating writeable v0.5.5 -> v0.6.1
    Updating yoke v0.7.5 -> v0.8.0
    Updating yoke-derive v0.7.5 -> v0.8.0
      Adding zerotrie v0.2.2
    Updating zerovec v0.10.4 -> v0.11.2
    Updating zerovec-derive v0.10.3 -> v0.11.1
2025-05-11 19:29:18 +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 cargo update 2025-05-11 19:29:18 +00:00
Cargo.toml Update mdbook to 0.4.49 2025-05-05 15:13:40 -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:

  1. Implement the preprocessor as a cargo library in the book's repository.
  2. 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"]
  1. Add the preprocessor as a dependency in rustbook's Cargo.toml.
  2. Call with_preprocessor in rustbook/src/main.rs.
  3. Be sure to test that it generates correctly, such as running ./x doc MY-BOOK-NAME --open and verify the content looks correct.
  4. Also test tidy and your book, such as running ./x test tidy and ./x test MY-BOOK-NAME.