1 files changed, 49 insertions, 0 deletions
diff --git a/src/doc/rustc-dev-guide/src/building/compiler-documenting.md b/src/doc/rustc-dev-guide/src/building/compiler-documenting.md
new file mode 100644
index 000000000..965e004c9
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/building/compiler-documenting.md
@@ -0,0 +1,49 @@
+# Building documentation
+
+This chapter describes how to build documentation of toolchain components,
+like the standard library (std) or the compiler (rustc).
+
+- Document everything
+
+  This uses `rustdoc` from the beta toolchain,
+  so will produce (slightly) different output to stage 1 rustdoc,
+  as rustdoc is under active development:
+
+  ```bash
+  ./x.py doc
+  ```
+
+  If you want to be sure the documentation looks the same as on CI:
+
+  ```bash
+  ./x.py doc --stage 1
+  ```
+
+  This ensures that (current) rustdoc gets built,
+  then that is used to document the components.
+
+- Much like running individual tests or building specific components,
+  you can build just the documentation you want:
+
+  ```bash
+  ./x.py doc src/doc/book
+  ./x.py doc src/doc/nomicon
+  ./x.py doc compiler library
+  ```
+
+- Document internal rustc items
+
+  Compiler documentation is not built by default.
+  To create it by default with `x.py doc`, modify `config.toml`:
+
+  ```toml
+  [build]
+  compiler-docs = true
+  ```
+
+  Note that when enabled,
+  documentation for internal compiler items will also be built.
+
+  NOTE: The documentation for the compiler is found at [this link].
+
+[this link]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/