mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

revamp doc-build chapter

This commit is contained in:
Tshepang Mbambo 2022-07-19 22:41:02 +02:00
parent f354a7433b
commit 13a6ec809d
1 changed files with 35 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

74
src/building/compiler-documenting.md
View File

@ -1,55 +1,51 @@
# Building documentation # Building documentation
You might want to build documentation of the various components You can run `rustdoc` directly on a file to make sure the HTML is correct,
available like the standard library. There’s two ways to go about this. which runs quickly.
You can run rustdoc directly on the file to make sure the HTML is A more conventional way is using `/x.py doc`.
correct, which is fast. Alternatively, you can build the documentation
as part of the build process through `x.py`. Both are viable methods
since documentation is more about the content.
## Document everything - Document everything
This uses the beta rustdoc, which usually but not always has the same output This uses `rustdoc` from the beta toolchain,
as stage 1 rustdoc. so will produce (slightly) different output to stage 1 rustdoc,
as `rustdoc` is under active development:
```bash ```bash
./x.py doc ./x.py doc
``` ```
## If you want to be sure that the links behave the same as on CI If you want to be sure the documentation looks the same as on CI:
```bash ```bash
./x.py doc --stage 1 ./x.py doc --stage 1
``` ```
First the compiler and rustdoc get built to make sure everything is okay First,
and then it documents the files. the compiler and rustdoc get built to make sure everything is okay,
and then it documents the files.
## Document specific components - Much like running individual tests or building specific components,
you can build just the documentation you want:
```bash ```bash
./x.py doc src/doc/book ./x.py doc src/doc/book
./x.py doc src/doc/nomicon ./x.py doc src/doc/nomicon
./x.py doc src/doc/book library ./x.py doc compiler library
``` ```
Much like individual tests or building certain components you can build only - Document internal rustc items
the documentation you want.
## Document internal rustc items Compiler documentation is not built by default.
To enable it, modify "config.toml":
Compiler documentation is not built by default. To enable it, modify config.toml: ```toml
[build]
compiler-docs = true
```
```toml Note that when enabled,
[build] documentation for internal compiler items will also be built.
compiler-docs = true
```
Note that when enabled, NOTE: The documentation for the compiler is found at [this link].
documentation for internal compiler items will also be built.
### Compiler Documentation [this link]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/
The documentation for the Rust components are found at [rustc doc].
[rustc doc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/