From 23dbd33d9372bdb422eeb3978f4af90faebfb989 Mon Sep 17 00:00:00 2001 From: Dylan MacKenzie Date: Tue, 28 Apr 2020 08:55:41 -0700 Subject: [PATCH 1/2] Direct contributors to try stage 0 rustdoc first --- CONTRIBUTING.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 051f5af7bc105..121aa1dbf0c60 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -393,10 +393,14 @@ You can find documentation style guidelines in [RFC 1574][rfc1574]. [rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text -In many cases, you don't need a full `./x.py doc`. You can use `rustdoc` directly -to check small fixes. For example, `rustdoc src/doc/reference.md` will render -reference to `doc/reference.html`. The CSS might be messed up, but you can -verify that the HTML is right. +In many cases, you don't need a full `./x.py doc`, which will build the entire +stage 2 compiler. When updating documentation for the standard library, first +try `./x.py doc --stage 0 src/libstd`. Results will should appear in +`build/$TARGET/crate-docs`. + +You can also use `rustdoc` directly to check small fixes. For example, +`rustdoc src/doc/reference.md` will render reference to `doc/reference.html`. +The CSS might be messed up, but you can verify that the HTML is right. Additionally, contributions to the [rustc-dev-guide] are always welcome. Contributions can be made directly at [the From 5577b3554d3d111f7cff683669b5f7d37539d18d Mon Sep 17 00:00:00 2001 From: Dylan MacKenzie Date: Tue, 28 Apr 2020 09:34:07 -0700 Subject: [PATCH 2/2] Suggest stage 1 if stage 0 fails --- CONTRIBUTING.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 121aa1dbf0c60..e674cf61b51e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -394,9 +394,13 @@ You can find documentation style guidelines in [RFC 1574][rfc1574]. [rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text In many cases, you don't need a full `./x.py doc`, which will build the entire -stage 2 compiler. When updating documentation for the standard library, first -try `./x.py doc --stage 0 src/libstd`. Results will should appear in -`build/$TARGET/crate-docs`. +stage 2 compiler and compile the various books published on +[doc.rust-lang.org]. When updating documentation for the standard library, +first try `./x.py doc --stage 0 src/libstd`. If that fails, or if you need to +see the output from the latest version of `rustdoc`, use `--stage 1` instead of +`--stage 0`. Results should appear in `build/$TARGET/crate-docs`. + +[doc.rust-lang.org]: htts://doc.rust-lang.org You can also use `rustdoc` directly to check small fixes. For example, `rustdoc src/doc/reference.md` will render reference to `doc/reference.html`.