|
| 1 | +# Documentation |
| 2 | + |
| 3 | +Cargo has several types of documentation that contributors work with: |
| 4 | + |
| 5 | +* [The Cargo Book] |
| 6 | + * The primary user-facing Cargo documentation |
| 7 | + * Source at <https://github.com/rust-lang/cargo/tree/master/src/doc> |
| 8 | + * Built with [mdbook] |
| 9 | + * Published through ["the doc publishing process"] |
| 10 | +* Man pages |
| 11 | + * Man pages of the `cargo` command |
| 12 | + * Built with [mdman] |
| 13 | + * Published through ["the doc publishing process"] |
| 14 | +* [Contributor guide] |
| 15 | + * This guide itself |
| 16 | + * Source at <https://github.com/rust-lang/cargo/tree/master/src/doc/contrib> |
| 17 | + * Published independently on GitHub Pages at |
| 18 | + <https://rust-lang.github.io/cargo/contrib> |
| 19 | + when committing to the master branch. |
| 20 | + |
| 21 | +[The Cargo Book]: https://doc.rust-lang.org/cargo/ |
| 22 | +[Crate API docs]: https://docs.rs/cargo |
| 23 | +[Contributor guide]: https://rust-lang.github.io/cargo/contrib |
| 24 | +[mdBook]: https://github.com/rust-lang/mdBook |
| 25 | +[mdman]: https://github.com/rust-lang/cargo/tree/master/crates/mdman/ |
| 26 | +["the doc publishing process"]: ../process/release.md#docs-publishing |
| 27 | + |
| 28 | +## Building the book |
| 29 | + |
| 30 | +Building the book requires [mdBook]. To get it: |
| 31 | + |
| 32 | +```console |
| 33 | +$ cargo install mdbook |
| 34 | +``` |
| 35 | + |
| 36 | +To build the book: |
| 37 | + |
| 38 | +```console |
| 39 | +$ mdbook build |
| 40 | +``` |
| 41 | + |
| 42 | +`mdbook` provides a variety of different commands and options to help you work |
| 43 | +on the book: |
| 44 | + |
| 45 | +* `mdbook build --open`: Build the book and open it in a web browser. |
| 46 | +* `mdbook serve`: Launches a web server on localhost. It also automatically |
| 47 | + rebuilds the book whenever any file changes and automatically reloads your |
| 48 | + web browser. |
| 49 | + |
| 50 | +The book contents are driven by a `SUMMARY.md` file, |
| 51 | +and every file must be linked there. |
| 52 | +See <https://rust-lang.github.io/mdBook/> for its usage. |
| 53 | + |
| 54 | +## Building the man pages |
| 55 | + |
| 56 | +The man pages use a tool called [mdman] to convert Markdown templates into several output formats. |
| 57 | +See <https://github.com/rust-lang/cargo/tree/master/crates/mdman/doc> |
| 58 | +for usage details and template syntax. |
| 59 | + |
| 60 | +The templates are located in |
| 61 | +<https://github.com/rust-lang/cargo/tree/master/src/doc/man> |
| 62 | +and are converted into three formats: |
| 63 | + |
| 64 | +1. Troff man pages --- used by the `cargo help` command, |
| 65 | + and by distributions to provide man pages which people can install, |
| 66 | + saved in <https://github.com/rust-lang/cargo/tree/master/src/etc/man>. |
| 67 | +2. Plain text --- used for embedded help on platforms without `man` (such as Windows), |
| 68 | + saved in <https://github.com/rust-lang/cargo/tree/master/src/doc/man/generated_txt>. |
| 69 | +3. Markdown (with some HTML) --- used for the Cargo Book, |
| 70 | + saved in <https://github.com/rust-lang/cargo/tree/master/src/doc/src/commands>. |
| 71 | + |
| 72 | +To rebuild the man pages, run `cargo build-man` inside the workspace. |
| 73 | + |
| 74 | +## Writing guidelines |
| 75 | + |
| 76 | +Cargo's documentation is a collective effort, |
| 77 | +so there isn't a single fixed writing style. |
| 78 | +We recommend following the style of the surrounding text to keep things consistent. |
| 79 | + |
| 80 | +A few important guidelines: |
| 81 | + |
| 82 | +* The [Cargo Commands](https://doc.rust-lang.org/nightly/cargo/commands/index.html) |
| 83 | + chapters in the book are generated from man page templates. |
| 84 | + To update them, see the [Building the man pages](#building-the-man-pages) section. |
| 85 | + Do not edit the generated Markdown files directly. |
| 86 | +* Links to pages under <https://doc.rust-lang.org/> should use relative paths. |
| 87 | + This ensures versioned docs are redirected correctly. |
| 88 | + For example, if you are at <https://doc.rust-lang.org/cargo/reference/config.html> |
| 89 | + and want to link to <https://doc.rust-lang.org/rustc/codegen-options/index.html>, |
| 90 | + you should write the link as `../../rustc/codegen-options/index.html`. |
| 91 | + This rule doesn't apply if you specifically want to link to docs of a fixed version or channel. |
| 92 | +* When renaming or removing any headings or pages, |
| 93 | + make sure to set up proper redirects via the [`output.html.redirect`] mdbook option. |
| 94 | +* If a section refers to a concept explained elsewhere |
| 95 | + (like profiles, features, or workspaces), link to it. |
| 96 | + That keeps the book navigable without duplicating content. |
| 97 | + |
| 98 | +[[`output.html.redirect`]]: https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlredirect |
| 99 | + |
| 100 | +## SemVer chapter tests |
| 101 | + |
| 102 | +There is a script to verify that the examples in [the SemVer chapter] work as |
| 103 | +intended. To run the tests, run `cargo +stable run -p semver-check`. |
| 104 | + |
| 105 | +Note that these tests run on the most recent stable release because they |
| 106 | +validate the output of the compiler diagnostics. The output can change between |
| 107 | +releases, so we pin to a specific release to avoid frequent and unexpected |
| 108 | +breakage. |
| 109 | + |
| 110 | +[the SemVer chapter]: https://doc.rust-lang.org/nightly/cargo/reference/semver.html |
0 commit comments