src/doc/rustc-dev-guide/src/building/compiler-documenting.md

   1 # Building documentation
   2
   3 This chapter describes how to build documentation of toolchain components,
   4 like the standard library (std) or the compiler (rustc).
   5
   6 - Document everything
   7
   8   This uses `rustdoc` from the beta toolchain,
   9   so will produce (slightly) different output to stage 1 rustdoc,
  10   as rustdoc is under active development:
  11
  12   ```bash
  13   ./x.py doc
  14   ```
  15
  16   If you want to be sure the documentation looks the same as on CI:
  17
  18   ```bash
  19   ./x.py doc --stage 1
  20   ```
  21
  22   This ensures that (current) rustdoc gets built,
  23   then that is used to document the components.
  24
  25 - Much like running individual tests or building specific components,
  26   you can build just the documentation you want:
  27
  28   ```bash
  29   ./x.py doc src/doc/book
  30   ./x.py doc src/doc/nomicon
  31   ./x.py doc compiler library
  32   ```
  33
  34   See [the nightly docs index page](https://doc.rust-lang.org/nightly/) for a full list of books.
  35
  36 - Document internal rustc items
  37
  38   Compiler documentation is not built by default.
  39   To create it by default with `x.py doc`, modify `config.toml`:
  40
  41   ```toml
  42   [build]
  43   compiler-docs = true
  44   ```
  45
  46   Note that when enabled,
  47   documentation for internal compiler items will also be built.
  48
  49   NOTE: The documentation for the compiler is found at [this link].
  50
  51 [this link]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/