From d9d7d95af1accdbf8478beda752b1e806a51135a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 30 Sep 2025 16:19:14 -0700 Subject: [PATCH] Rearrange the README a little This rearranges the README a little, since I felt like the current organization was a little awkward. This hopefully has a little more of a better organization. --- README.md | 69 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 35 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index e152a28fb2..86804ff33a 100644 --- a/README.md +++ b/README.md @@ -3,26 +3,14 @@ This document is the primary reference for the Rust programming language. -## Dependencies +## Contributor docs -- Nightly Rust -- [mdbook](https://rust-lang.github.io/mdBook/) +There are several pages for those working on the reference: -## Installing dependencies - -First, ensure that you have a recent copy of the nightly Rust compiler -installed, as this is needed in order to run the tests: - -```sh -rustup toolchain install nightly -``` - -Now, ensure you have `mdbook` installed, as this is needed in order to -build the Reference: - -```sh -cargo install --locked mdbook -``` +* [Authoring guide](https://github.com/rust-lang/reference/blob/master/docs/authoring.md): Guidelines for writing content. +* [Review policy](https://github.com/rust-lang/reference/blob/master/docs/review-policy.md): Guidelines for reviewers. +* [Grammar](https://github.com/rust-lang/reference/blob/master/docs/grammar.md): How the grammar syntax works. +* [Attribute template](https://github.com/rust-lang/reference/blob/master/docs/attribute-template.md): The standard template for documenting an attribute. ## Building @@ -30,6 +18,7 @@ To build the Reference, first clone the project: ```sh git clone https://github.com/rust-lang/reference.git +cd reference ``` (Alternatively, if you don't want to use `git`, [download][] a ZIP file @@ -38,39 +27,42 @@ top-level directory to `reference`.) [download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip -Now change your current directory to the working directory: +### Installing mdbook -```sh -cd reference -``` +The Reference is built using [mdbook]. -To test all of the code examples in the Reference, run: +First, ensure that you have a recent copy of the nightly Rust compiler installed, as this is needed in order to run the tests: ```sh -mdbook test +rustup toolchain install nightly +rustup override set nightly ``` -For authors, consider using the server functionality which supports automatic reload. - -To build the Reference locally (in `book/`) and open it in a web -browser, run: +Now, ensure you have `mdbook` installed, as this is needed in order to build the Reference: ```sh -SPEC_RELATIVE=0 mdbook build --open +cargo install --locked mdbook ``` -This will open a browser with a websocket live-link to automatically reload whenever the source is updated. +[mdbook]: https://rust-lang.github.io/mdBook/ -You can also use mdbook's live webserver option, which will automatically rebuild the book and reload your web browser whenever a source file is modified: +### Running mdbook -```sh -SPEC_RELATIVE=0 mdbook serve --open -``` +`mdbook` provides a variety of different commands and options to help you work on the book: + +* `mdbook build --open`: Build the book and open it in a web browser. +* `mdbook serve --open`: Launches a web server on localhost. It also automatically rebuilds the book whenever any file changes and automatically reloads your web browser. + +The book contents are driven by a `SUMMARY.md` file, and every file must be linked there. See for its usage. ### `SPEC_RELATIVE` The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to instead of being relative, which is useful when viewing locally since you normally don't have a copy of the standard library. +```sh +SPEC_RELATIVE=0 mdbook serve --open +``` + The published site at (or local docs using `rustup doc`) does not set this, which means it will use relative links which supports offline viewing and links to the correct version (for example, links in will stay within the 1.81.0 directory). ### `SPEC_DENY_WARNINGS` @@ -80,3 +72,12 @@ The `SPEC_DENY_WARNINGS=1` environment variable will turn all warnings generated ### `SPEC_RUST_ROOT` The `SPEC_RUST_ROOT` can be used to point to the directory of a checkout of . This is used by the test-linking feature so that it can find tests linked to reference rules. If this is not set, then the tests won't be linked. + +## Running tests + +There are several different kinds of tests you can run (these are enforced on CI): + +* `mdbook test`: This will run the inline Rust codeblocks (internally it uses `rustdoc` to do this). +* `cargo xtask style-check`: This will validate some style checks (see [authoring guide](docs/authoring.md)). +* `cargo xtask linkcheck`: This will validate that markdown links aren't broken. +* `cargo xtask test-all`: Runs all tests.