From 66f0e32f04ab9de8030a214b342fc2f4cac50239 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Tue, 19 Jul 2022 22:41:02 +0200 Subject: [PATCH 1/6] revamp doc-build chapter --- src/building/compiler-documenting.md | 74 +++++++++++++--------------- 1 file changed, 35 insertions(+), 39 deletions(-) diff --git a/src/building/compiler-documenting.md b/src/building/compiler-documenting.md index ba6a2999b..64b139e10 100644 --- a/src/building/compiler-documenting.md +++ b/src/building/compiler-documenting.md @@ -1,55 +1,51 @@ # Building documentation -You might want to build documentation of the various components -available like the standard library. There’s two ways to go about this. -You can run rustdoc directly on the file to make sure the HTML is -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. +You can run `rustdoc` directly on a file to make sure the HTML is correct, +which runs quickly. +A more conventional way is using `/x.py doc`. -## Document everything +- Document everything -This uses the beta rustdoc, which usually but not always has the same output -as stage 1 rustdoc. + 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 -``` + ```bash + ./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 -./x.py doc --stage 1 -``` + ```bash + ./x.py doc --stage 1 + ``` -First the compiler and rustdoc get built to make sure everything is okay -and then it documents the files. + First, + 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 -./x.py doc src/doc/book -./x.py doc src/doc/nomicon -./x.py doc src/doc/book library -``` + ```bash + ./x.py doc src/doc/book + ./x.py doc src/doc/nomicon + ./x.py doc compiler library + ``` -Much like individual tests or building certain components you can build only - the documentation you want. +- Document internal rustc items -## 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 -[build] -compiler-docs = true -``` + Note that when enabled, + documentation for internal compiler items will also be built. -Note that when enabled, -documentation for internal compiler items will also be built. + NOTE: The documentation for the compiler is found at [this link]. -### Compiler Documentation - -The documentation for the Rust components are found at [rustc doc]. - -[rustc doc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ +[this link]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ From 9355ef4918e590ec679c2ef42c9b98d4402e7a32 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Sat, 23 Jul 2022 00:16:33 +0200 Subject: [PATCH 2/6] Update src/building/compiler-documenting.md Co-authored-by: Yuki Okushi --- src/building/compiler-documenting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/building/compiler-documenting.md b/src/building/compiler-documenting.md index 64b139e10..bc7bdc0f6 100644 --- a/src/building/compiler-documenting.md +++ b/src/building/compiler-documenting.md @@ -36,7 +36,7 @@ A more conventional way is using `/x.py doc`. - Document internal rustc items Compiler documentation is not built by default. - To enable it, modify "config.toml": + To enable it, modify `config.toml`: ```toml [build] From 431ada163da6352269e28a3946e41c4235318554 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Sun, 31 Jul 2022 00:21:45 +0200 Subject: [PATCH 3/6] summary of chapter --- src/building/compiler-documenting.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/building/compiler-documenting.md b/src/building/compiler-documenting.md index bc7bdc0f6..7c52b4b81 100644 --- a/src/building/compiler-documenting.md +++ b/src/building/compiler-documenting.md @@ -1,8 +1,7 @@ # Building documentation -You can run `rustdoc` directly on a file to make sure the HTML is correct, -which runs quickly. -A more conventional way is using `/x.py doc`. +This chapter describes how to build documentation of toolchain components, +either in whole or individually. - Document everything From 90c7bc22e1d11c20f22d653bba038479c773a0a3 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Sun, 31 Jul 2022 01:01:58 +0200 Subject: [PATCH 4/6] try address review comments --- src/building/compiler-documenting.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/building/compiler-documenting.md b/src/building/compiler-documenting.md index 7c52b4b81..9ed5c262b 100644 --- a/src/building/compiler-documenting.md +++ b/src/building/compiler-documenting.md @@ -1,13 +1,13 @@ # Building documentation This chapter describes how to build documentation of toolchain components, -either in whole or individually. +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: + as rustdoc is under active development: ```bash ./x.py doc @@ -20,8 +20,8 @@ either in whole or individually. ``` First, - the compiler and rustdoc get built to make sure everything is okay, - and then it documents the files. + the compiler gets built to make sure rustdoc compiles, + then that newly-built rustdoc is used to document the components. - Much like running individual tests or building specific components, you can build just the documentation you want: From 8b3d8b18fa1dcb341f062f9610c57f05176a077a Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Sun, 31 Jul 2022 07:09:06 +0200 Subject: [PATCH 5/6] accept review suggestion Co-authored-by: Joshua Nelson --- src/building/compiler-documenting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/building/compiler-documenting.md b/src/building/compiler-documenting.md index 9ed5c262b..202923b68 100644 --- a/src/building/compiler-documenting.md +++ b/src/building/compiler-documenting.md @@ -35,7 +35,7 @@ like the standard library (std) or the compiler (rustc). - Document internal rustc items Compiler documentation is not built by default. - To enable it, modify `config.toml`: + To create it by default with `x.py doc`, modify `config.toml`: ```toml [build] From e447e362209827c4ad1b7caaf0abd3cd752cc4c8 Mon Sep 17 00:00:00 2001 From: Tshepang Mbambo Date: Sun, 31 Jul 2022 07:40:37 +0200 Subject: [PATCH 6/6] address review comment https://github.com/rust-lang/rustc-dev-guide/pull/1402#discussion_r933905339 --- src/building/compiler-documenting.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/building/compiler-documenting.md b/src/building/compiler-documenting.md index 202923b68..965e004c9 100644 --- a/src/building/compiler-documenting.md +++ b/src/building/compiler-documenting.md @@ -19,9 +19,8 @@ like the standard library (std) or the compiler (rustc). ./x.py doc --stage 1 ``` - First, - the compiler gets built to make sure rustdoc compiles, - then that newly-built rustdoc is used to document the components. + 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: