From 974efef192cd14725e7b3ac6861966adc024cefc Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Sun, 17 Aug 2025 19:38:54 -0400 Subject: [PATCH] docs(contrib): polish documentation guide and make it a chapter --- src/doc/contrib/src/SUMMARY.md | 1 + src/doc/contrib/src/documentation/index.md | 98 +++++++++++++++------- 2 files changed, 69 insertions(+), 30 deletions(-) diff --git a/src/doc/contrib/src/SUMMARY.md b/src/doc/contrib/src/SUMMARY.md index 4fe7d3cd0..067bfbb63 100644 --- a/src/doc/contrib/src/SUMMARY.md +++ b/src/doc/contrib/src/SUMMARY.md @@ -24,3 +24,4 @@ - [Writing Tests](./tests/writing.md) - [Benchmarking and Profiling](./tests/profiling.md) - [Crater](./tests/crater.md) +- [Documentation](./documentation/index.md) diff --git a/src/doc/contrib/src/documentation/index.md b/src/doc/contrib/src/documentation/index.md index c9bbaac00..0ef8b6d9c 100644 --- a/src/doc/contrib/src/documentation/index.md +++ b/src/doc/contrib/src/documentation/index.md @@ -1,14 +1,31 @@ -# Cargo documentation +# Documentation -This directory contains Cargo's documentation. There are two parts, [The Cargo -Book] which is built with [mdbook] and the man pages, which are built with -[mdman]. +Cargo has several types of documentation that contributors work with: + +* [The Cargo Book] + * The primary user-facing Cargo documentation + * Source at + * 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 + * Published independently on GitHub Pages at + + when committing to the master branch. [The Cargo Book]: https://doc.rust-lang.org/cargo/ +[Crate API docs]: https://docs.rs/cargo +[Contributor guide]: https://rust-lang.github.io/cargo/contrib [mdBook]: https://github.com/rust-lang/mdBook [mdman]: https://github.com/rust-lang/cargo/tree/master/crates/mdman/ +["the doc publishing process"]: ../process/release.md#docs-publishing -### Building the book +## Building the book Building the book requires [mdBook]. To get it: @@ -30,31 +47,59 @@ on the book: rebuilds the book whenever any file changes and automatically reloads your web browser. -The book contents are driven by the [`SUMMARY.md`](src/SUMMARY.md) file, and -every file must be linked there. +The book contents are driven by a `SUMMARY.md` file, +and every file must be linked there. +See for its usage. -### Building the man pages +## Building the man pages -The man pages use a tool called [mdman] to convert markdown to a man page -format. Check out the documentation at -[`mdman/doc/`](../../crates/mdman/doc/) -for more details. +The man pages use a tool called [mdman] to convert Markdown templates into several output formats. +See +for usage details and template syntax. -The man pages are converted from a templated markdown (located in the -[`src/doc/man/`](man) -directory) to three different formats: +The templates are located in + +and are converted into three formats: -1. Troff-style man pages, saved in [`src/etc/man/`](../etc/man). -2. Markdown (with some HTML) for the Cargo Book, saved in - [`src/doc/src/commands/`](src/commands). -3. Plain text (needed for embedded man pages on platforms without man such as - Windows), saved in [`src/doc/man/generated_txt/`](man/generated_txt). +1. Troff man pages --- used by the `cargo help` command, + and by distributions to provide man pages which people can install, + saved in . +2. Plain text --- used for embedded help on platforms without `man` (such as Windows), + saved in . +3. Markdown (with some HTML) --- used for the Cargo Book, + saved in . To rebuild the man pages, run `cargo build-man` inside the workspace. -### SemVer chapter tests +## Writing guidelines -There is a script to verify that the examples in the SemVer chapter work as +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](https://doc.rust-lang.org/nightly/cargo/commands/index.html) + chapters in the book are generated from man page templates. + To update them, see the [Building the man pages](#building-the-man-pages) section. + Do not edit the generated Markdown files directly. +* Links to pages under should use relative paths. + This ensures versioned docs are redirected correctly. + For example, if you are at + and want to link to , + 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 @@ -62,11 +107,4 @@ 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. -## Contributing - -We'd love your help with improving the documentation! Please feel free to -[open issues](https://github.com/rust-lang/cargo/issues) about anything, and -send in PRs for things you'd like to fix or change. If your change is large, -please open an issue first, so we can make sure that it's something we'd -accept before you go through the work of getting a PR together. - +[the SemVer chapter]: https://doc.rust-lang.org/nightly/cargo/reference/semver.html