Documentation

Cargo has several types of documentation that contributors work with:

• The Cargo Book
  • The primary user-facing Cargo documentation
  • Source at https://github.com/rust-lang/cargo/tree/master/doc/book
  • Built with mdbook
  • Published through “the doc publishing process”
• Man pages
  • Man pages of the cargo command
  • Built with mdman
  • Published through “the doc publishing process”
• Contributor guide
  • This guide itself
  • Source at https://github.com/rust-lang/cargo/tree/master/doc/contrib
  • Published independently on GitHub Pages at https://rust-lang.github.io/cargo/contrib when committing to the master branch.

Building the book

Building the book requires mdBook. To get it:

$ cargo install mdbook

To build the book:

$ mdbook build

mdbook provides a variety of different commands and options to help you work on the book:

• mdbook build --open: Build the book and open it in a web browser.
• mdbook serve: Launches a web server on localhost. It also automatically rebuilds the book whenever any file changes and automatically reloads your web browser.

The book contents are driven by a SUMMARY.md file, and every file must be linked there. See https://rust-lang.github.io/mdBook/ for its usage.

Building the man pages

The man pages use a tool called mdman to convert Markdown templates into several output formats. See https://github.com/rust-lang/cargo/tree/master/crates/mdman/doc for usage details and template syntax.

The templates are located in https://github.com/rust-lang/cargo/tree/master/doc/man and are converted into three formats:

1. Troff man pages --- used by the cargo help command, and by distributions to provide man pages which people can install, saved in https://github.com/rust-lang/cargo/tree/master/etc/man.
2. Plain text --- used for embedded help on platforms without man (such as Windows), saved in https://github.com/rust-lang/cargo/tree/master/doc/man/generated_txt.
3. Markdown (with some HTML) --- used for the Cargo Book, saved in https://github.com/rust-lang/cargo/tree/master/doc/book/src/commands.

To rebuild the man pages, run cargo build-man inside the workspace.

Writing guidelines

Cargo‘s documentation is a collective effort, so there isn’t a single fixed writing style. We recommend following the style of the surrounding text to keep things consistent.

A few important guidelines:

• The Cargo Commands chapters in the book are generated from man page templates. To update them, see the Building the man pages section. Do not edit the generated Markdown files directly.
• Links to pages under https://doc.rust-lang.org/ should use relative paths. This ensures versioned docs are redirected correctly. For example, if you are at https://doc.rust-lang.org/cargo/reference/config.html and want to link to https://doc.rust-lang.org/rustc/codegen-options/index.html, you should write the link as ../../rustc/codegen-options/index.html. This rule doesn't apply if you specifically want to link to docs of a fixed version or channel.
• When renaming or removing any headings or pages, make sure to set up proper redirects via the [output.html.redirect] mdbook option.
• If a section refers to a concept explained elsewhere (like profiles, features, or workspaces), link to it. That keeps the book navigable without duplicating content.

[[output.html.redirect]]: https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlredirect

SemVer chapter tests

There is a script to verify that the examples in the SemVer chapter work as intended. To run the tests, run cargo +stable run -p semver-check.

Note that these tests run on the most recent stable release because they validate the output of the compiler diagnostics. The output can change between releases, so we pin to a specific release to avoid frequent and unexpected breakage.