Skip to content

Commit a341cb4

Browse files
stegramsstegrams
authored
Merge branch 'master' into patch-1
2 parents c83ceb4 + d6d24b9 commit a341cb4

File tree

122 files changed

+8619
-1408
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

122 files changed

+8619
-1408
lines changed

‎.github/workflows/main.yml

Lines changed: 126 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,9 +3,11 @@ on:
33
pull_request:
44
merge_group:
55

6+
env:
7+
MDBOOK_VERSION: 0.4.43
8+
69
jobs:
7-
test:
8-
name: Test
10+
code-tests:
911
runs-on: ubuntu-latest
1012
steps:
1113
- uses: actions/checkout@master
@@ -14,12 +16,12 @@ jobs:
1416
- name: Install Rust
1517
run: |
1618
rustup set profile minimal
17-
rustup toolchain install nightly -c rust-docs
19+
rustup toolchain install nightly
1820
rustup default nightly
1921
- name: Install mdbook
2022
run: |
2123
mkdir bin
22-
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.14/mdbook-v0.4.14-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
24+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
2325
echo "$(pwd)/bin" >> $GITHUB_PATH
2426
- name: Report versions
2527
run: |
@@ -28,10 +30,129 @@ jobs:
2830
mdbook --version
2931
- name: Run tests
3032
run: mdbook test
33+
34+
style-tests:
35+
runs-on: ubuntu-latest
36+
steps:
37+
- uses: actions/checkout@master
38+
- name: Checkout rust-lang/rust
39+
uses: actions/checkout@master
40+
with:
41+
repository: rust-lang/rust
42+
path: rust
43+
- name: Update rustup
44+
run: rustup self update
45+
- name: Install Rust
46+
run: |
47+
rustup set profile minimal
48+
rustup toolchain install nightly -c rust-docs,rustfmt
49+
rustup default nightly
50+
- name: Install mdbook
51+
run: |
52+
mkdir bin
53+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
54+
echo "$(pwd)/bin" >> $GITHUB_PATH
55+
- name: Report versions
56+
run: |
57+
rustup --version
58+
rustc -Vv
59+
mdbook --version
3160
- name: Style checks
32-
run: (cd style-check && cargo run -- ../src)
61+
working-directory: style-check
62+
run: cargo run --locked -- ../src
63+
- name: Style fmt
64+
working-directory: style-check
65+
run: cargo fmt --check
66+
- name: Verify the book builds
67+
env:
68+
SPEC_DENY_WARNINGS: 1
69+
SPEC_RUST_ROOT: ${{ github.workspace }}/rust
70+
run: mdbook build
3371
- name: Check for broken links
3472
run: |
3573
curl -sSLo linkcheck.sh \
3674
https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
3775
sh linkcheck.sh --all reference
76+
77+
mdbook-spec:
78+
runs-on: ubuntu-latest
79+
steps:
80+
- uses: actions/checkout@master
81+
- name: Update rustup
82+
run: rustup self update
83+
- name: Install Rust
84+
run: |
85+
rustup set profile minimal
86+
rustup toolchain install nightly -c rustfmt
87+
rustup default nightly
88+
- name: Install mdbook
89+
run: |
90+
mkdir bin
91+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
92+
echo "$(pwd)/bin" >> $GITHUB_PATH
93+
- name: Report versions
94+
run: |
95+
rustup --version
96+
rustc -Vv
97+
- name: Verify mdbook-spec lockfile is current
98+
working-directory: ./mdbook-spec
99+
run: cargo update -p mdbook-spec --locked
100+
- name: Test mdbook-spec
101+
working-directory: ./mdbook-spec
102+
run: cargo test
103+
- name: Rustfmt check
104+
working-directory: ./mdbook-spec
105+
run: cargo fmt --check
106+
107+
preview:
108+
if: github.event_name == 'pull_request'
109+
runs-on: ubuntu-latest
110+
steps:
111+
- uses: actions/checkout@master
112+
- name: Checkout rust-lang/rust
113+
uses: actions/checkout@master
114+
with:
115+
repository: rust-lang/rust
116+
path: rust
117+
- name: Update rustup
118+
run: rustup self update
119+
- name: Install Rust
120+
run: |
121+
rustup set profile minimal
122+
rustup toolchain install nightly
123+
rustup default nightly
124+
- name: Install mdbook
125+
run: |
126+
mkdir bin
127+
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v${MDBOOK_VERSION}/mdbook-v${MDBOOK_VERSION}-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=bin
128+
echo "$(pwd)/bin" >> $GITHUB_PATH
129+
- name: Build the book
130+
env:
131+
SPEC_RELATIVE: 0
132+
SPEC_RUST_ROOT: ${{ github.workspace }}/rust
133+
run: mdbook build --dest-dir dist/preview-${{ github.event.pull_request.number }}
134+
- name: Upload artifact
135+
uses: actions/upload-artifact@v4
136+
with:
137+
name: preview-${{ github.event.pull_request.number }}
138+
overwrite: true
139+
path: dist
140+
141+
# The success job is here to consolidate the total success/failure state of
142+
# all other jobs. This job is then included in the GitHub branch protection
143+
# rule which prevents merges unless all other jobs are passing. This makes
144+
# it easier to manage the list of jobs via this yml file and to prevent
145+
# accidentally adding new jobs without also updating the branch protections.
146+
success:
147+
name: Success gate
148+
if: always()
149+
needs:
150+
- code-tests
151+
- style-tests
152+
- mdbook-spec
153+
# preview is explicitly excluded here since it doesn't run on merge
154+
runs-on: ubuntu-latest
155+
steps:
156+
- run: jq --exit-status 'all(.result == "success")' <<< '${{ toJson(needs) }}'
157+
- name: Done
158+
run: exit 0

‎CONTRIBUTING.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,10 @@ for the Reference. As such, we have the warning saying there's work that needs
1414
to be done. Eventually, we plan to make sure everything is well documented
1515
enough that we can remove the warning.
1616

17-
It is encouraged for you to read the [introduction] to familiarize yourself
18-
with the kind of content the reference is expected to contain and the
19-
conventions it uses. Also, the [style guide] provides more detailed guidelines
20-
for formatting and content.
17+
It is encouraged for you to read the [introduction] to familiarize yourself with
18+
the kind of content the reference is expected to contain and the conventions it
19+
uses. Also, the [Authoring Guide] provides more detailed guidelines for
20+
formatting and content.
2121

2222
## Critiquing the Reference
2323

@@ -68,9 +68,9 @@ This should include links to any relevant information, such as the
6868
stabilization PR, the RFC, the tracking issue, and anything else that would be
6969
helpful for writing the documentation.
7070

71+
[Authoring Guide]: docs/authoring.md
7172
[introduction]: src/introduction.md
7273
[issue tracker]: https://github.com/rust-lang/reference/issues
7374
[playpen]: https://play.rust-lang.org/
7475
[rust-lang/rust]: https://github.com/rust-lang/rust/
75-
[style guide]: STYLE.md
7676
[unstable]: https://doc.rust-lang.org/nightly/unstable-book/

‎README.md

Lines changed: 52 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# The Rust Language Reference
22

3-
This document is the primary reference for the Rust programming language.
3+
This document is the primary reference for the Rust programming
4+
language.
45

56
This document is not normative. It may include details that are specific
67
to `rustc` itself, and should not be taken as a specification for the
@@ -9,52 +10,78 @@ what we have for now.
910

1011
## Dependencies
1112

12-
- rustc (the Rust compiler).
13-
- [mdbook](https://rust-lang.github.io/mdBook/) (use `cargo install mdbook` to install it).
14-
- rust nightly (you would be required to set your Rust version to the nightly version to make sure all tests pass)
13+
- Nightly Rust
14+
- [mdbook](https://rust-lang.github.io/mdBook/)
1515

16-
## Build steps
16+
## Installing dependencies
1717

18-
To build the project, follow the steps given below :
18+
First, ensure that you have a recent copy of the nightly Rust compiler
19+
installed, as this is needed in order to run the tests:
1920

20-
Clone the project by downloading the ZIP from the [GitHub page](https://github.com/rust-lang/reference) or
21-
run the following command:
22-
23-
```
24-
git clone https://github.com/rust-lang/reference
21+
```sh
22+
rustup toolchain install nightly
2523
```
2624

27-
Change the directory to the downloaded repository:
25+
Now, ensure you have `mdbook` installed, as this is needed in order to
26+
build the Reference:
2827

2928
```sh
30-
cd reference
29+
cargo install --locked mdbook
3130
```
3231

33-
To run the tests, you would need to set the Rust version to the nightly release. You can do this by executing the following command:
32+
## Building
33+
34+
To build the Reference, first clone the project:
3435

35-
```shell
36-
rustup override set nightly
36+
```sh
37+
git clone https://github.com/rust-lang/reference.git
3738
```
3839

39-
This will set the nightly version only for your the current project.
40+
(Alternatively, if you don't want to use `git`, [download][] a ZIP file
41+
of the project, extract it using your preferred tool, and rename the
42+
top-level directory to `reference`.)
4043

41-
If you wish to set Rust nightly for all your projects, you can run the command:
44+
[download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip
4245

43-
```shell
44-
rustup default nightly
46+
Now change your current directory to the working directory:
47+
48+
```sh
49+
cd reference
4550
```
4651

47-
Now, run the following command to test the code snippets to catch compilation errors:
52+
To test all of the code examples in the Reference, run:
4853

49-
```shell
54+
```sh
5055
mdbook test
5156
```
5257

58+
For authors, consider using the server functionality which supports automatic reload.
5359

54-
To generate a local instance of the book, run:
60+
To build the Reference locally (in `build/`) and open it in a web
61+
browser, run:
5562

5663
```sh
57-
mdbook build
64+
SPEC_RELATIVE=0 mdbook build --open
5865
```
5966

60-
The generated HTML will be in the `book` folder.
67+
This will open a browser with a websocket live-link to automatically reload whenever the source is updated.
68+
69+
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:
70+
71+
```sh
72+
SPEC_RELATIVE=0 mdbook serve --open
73+
```
74+
75+
### `SPEC_RELATIVE`
76+
77+
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.
78+
79+
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).
80+
81+
### `SPEC_DENY_WARNINGS`
82+
83+
The `SPEC_DENY_WARNINGS=1` environment variable will turn all warnings generated by `mdbook-spec` to errors. This is used in CI to ensure that there aren't any problems with the book content.
84+
85+
### `SPEC_RUST_ROOT`
86+
87+
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.

‎STYLE.md

Lines changed: 2 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,71 +1,5 @@
11
# Rust reference style guide
22

3-
Some conventions and content guidelines are specified in the [introduction].
4-
This document serves as a guide for editors and reviewers.
3+
See the [Authoring Guide] for details on the style used in the reference.
54

6-
There is a [`style-check`](style-check/) tool which is run in CI to check some of these. To use it locally, run `cargo run --manifest-path=style-check/Cargo.toml src`.
7-
8-
## Markdown formatting
9-
10-
* Use ATX-style heading with sentence case.
11-
* Use one line per sentence to make diffs nicer.
12-
Do not wrap long lines.
13-
* Use reference links, with shortcuts if appropriate.
14-
Place the sorted link reference definitions at the bottom of the file, or at the bottom of a section if there is an unusually large number of links that are specific to the section.
15-
16-
```
17-
Example of shortcut link: [enumerations]
18-
Example of reference link with label: [block expression][block]
19-
20-
[block]: expressions/block-expr.md
21-
[enumerations]: types/enum.md
22-
```
23-
24-
* Links should be relative with the `.md` extension.
25-
Links to other rust-lang books that are published with the reference or the standard library API should also be relative so that the linkchecker can validate them.
26-
* See the [Conventions] section for formatting callouts such as notes, edition differences, and warnings.
27-
* Formatting to avoid:
28-
* Avoid trailing spaces.
29-
* Avoid double blank lines.
30-
31-
### Code examples
32-
33-
Code examples should use code blocks with triple backticks.
34-
The language should always be specified (such as `rust`).
35-
36-
```rust
37-
println!("Hello!");
38-
```
39-
40-
See https://highlightjs.org/ for a list of supported languages.
41-
42-
Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail:
43-
44-
* `edition2015` or `edition2018` — If it is edition-specific (see `book.toml` for the default).
45-
* `no_run` — The example should compile successfully, but should not be executed.
46-
* `should_panic` — The example should compile and run, but produce a panic.
47-
* `compile_fail` — The example is expected to fail to compile.
48-
* `ignore` — The example shouldn't be built or tested.
49-
This should be avoided if possible.
50-
Usually this is only necessary when the testing framework does not support it (such as external crates or modules, or a proc-macro), or it contains pseudo-code which is not valid Rust.
51-
An HTML comment such as `<!-- ignore: requires extern crate -->` should be placed before the example to explain why it is ignored.
52-
53-
See the [rustdoc documentation] for more detail.
54-
55-
## Language and grammar
56-
57-
* Use American English spelling.
58-
* Use Oxford commas.
59-
* Idioms and styling to avoid:
60-
* Avoid slashes for alternatives ("program/binary"), use conjunctions or rewrite it ("program or binary").
61-
* Avoid qualifying something as "in Rust", the entire reference is about Rust.
62-
63-
## Content
64-
65-
* Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block.
66-
The main text should stick to what is common between the editions.
67-
However, for large differences (such as "async"), the main text may contain edition-specific content as long as it is made clear which editions it applies to.
68-
69-
[conventions]: src/introduction.md#conventions
70-
[introduction]: src/introduction.md
71-
[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html
5+
[Authoring Guide]: docs/authoring.md

‎book.toml

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,21 @@ author = "The Rust Project Developers"
55

66
[output.html]
77
additional-css = ["theme/reference.css"]
8+
additional-js = ["theme/reference.js"]
89
git-repository-url = "https://github.com/rust-lang/reference/"
910
edit-url-template = "https://github.com/rust-lang/reference/edit/master/{path}"
11+
smart-punctuation = true
1012

1113
[output.html.redirect]
1214
"/expressions/enum-variant-expr.html" = "struct-expr.html"
1315
"/unsafe-blocks.html" = "unsafe-keyword.html"
1416
"/unsafe-functions.html" = "unsafe-keyword.html"
1517

1618
[rust]
17-
edition = "2021"
19+
edition = "2024"
20+
21+
[preprocessor.spec]
22+
command = "cargo run --release --manifest-path mdbook-spec/Cargo.toml"
23+
24+
[build]
25+
extra-watch-dirs = ["mdbook-spec/src"]

0 commit comments

Comments
 (0)