Skip to content

Rearrange the README a little #2029

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Rearrange the README a little #2029

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 35 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,33 +3,22 @@
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

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
Expand All @@ -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 <https://rust-lang.github.io/mdBook/> for its usage.

### `SPEC_RELATIVE`

The `SPEC_RELATIVE=0` environment variable makes links to the standard library go to <https://doc.rust-lang.org/> 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 <https://doc.rust-lang.org/reference/> (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 <https://doc.rust-lang.org/1.81.0/reference/> will stay within the 1.81.0 directory).

### `SPEC_DENY_WARNINGS`
Expand All @@ -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 <https://github.com/rust-lang/rust>. 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.