Merge branch 'master' into patch-1

.github/workflows/main.yml

@@ -3,9 +3,11 @@ on:
   pull_request:
   merge_group:
 
+env:
+  MDBOOK_VERSION: 0.4.43
+
 jobs:
-  test:
-    name: Test
+  code-tests:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@master
@@ -14,12 +16,12 @@ jobs:
     - name: Install Rust
       run: |
         rustup set profile minimal
-        rustup toolchain install nightly -c rust-docs
+        rustup toolchain install nightly
         rustup default nightly
     - name: Install mdbook
       run: |
         mkdir bin
-        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
+        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
         echo "$(pwd)/bin" >> $GITHUB_PATH
     - name: Report versions
       run: |
@@ -28,10 +30,129 @@ jobs:
         mdbook --version
     - name: Run tests
       run: mdbook test
+
+  style-tests:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+    - name: Checkout rust-lang/rust
+      uses: actions/checkout@master
+      with:
+        repository: rust-lang/rust
+        path: rust
+    - name: Update rustup
+      run: rustup self update
+    - name: Install Rust
+      run: |
+        rustup set profile minimal
+        rustup toolchain install nightly -c rust-docs,rustfmt
+        rustup default nightly
+    - name: Install mdbook
+      run: |
+        mkdir bin
+        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
+        echo "$(pwd)/bin" >> $GITHUB_PATH
+    - name: Report versions
+      run: |
+        rustup --version
+        rustc -Vv
+        mdbook --version
     - name: Style checks
-      run: (cd style-check && cargo run -- ../src)
+      working-directory: style-check
+      run: cargo run --locked -- ../src
+    - name: Style fmt
+      working-directory: style-check
+      run: cargo fmt --check
+    - name: Verify the book builds
+      env:
+        SPEC_DENY_WARNINGS: 1
+        SPEC_RUST_ROOT: ${{ github.workspace }}/rust
+      run: mdbook build
     - name: Check for broken links
       run: |
         curl -sSLo linkcheck.sh \
           https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
         sh linkcheck.sh --all reference
+
+  mdbook-spec:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+    - name: Update rustup
+      run: rustup self update
+    - name: Install Rust
+      run: |
+        rustup set profile minimal
+        rustup toolchain install nightly -c rustfmt
+        rustup default nightly
+    - name: Install mdbook
+      run: |
+        mkdir bin
+        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
+        echo "$(pwd)/bin" >> $GITHUB_PATH
+    - name: Report versions
+      run: |
+        rustup --version
+        rustc -Vv
+    - name: Verify mdbook-spec lockfile is current
+      working-directory: ./mdbook-spec
+      run: cargo update -p mdbook-spec --locked
+    - name: Test mdbook-spec
+      working-directory: ./mdbook-spec
+      run: cargo test
+    - name: Rustfmt check
+      working-directory: ./mdbook-spec
+      run: cargo fmt --check
+
+  preview:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+    - name: Checkout rust-lang/rust
+      uses: actions/checkout@master
+      with:
+        repository: rust-lang/rust
+        path: rust
+    - name: Update rustup
+      run: rustup self update
+    - name: Install Rust
+      run: |
+        rustup set profile minimal
+        rustup toolchain install nightly
+        rustup default nightly
+    - name: Install mdbook
+      run: |
+        mkdir bin
+        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
+        echo "$(pwd)/bin" >> $GITHUB_PATH
+    - name: Build the book
+      env:
+        SPEC_RELATIVE: 0
+        SPEC_RUST_ROOT: ${{ github.workspace }}/rust
+      run: mdbook build --dest-dir dist/preview-${{ github.event.pull_request.number }}
+    - name: Upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: preview-${{ github.event.pull_request.number }}
+        overwrite: true
+        path: dist
+
+  # The success job is here to consolidate the total success/failure state of
+  # all other jobs. This job is then included in the GitHub branch protection
+  # rule which prevents merges unless all other jobs are passing. This makes
+  # it easier to manage the list of jobs via this yml file and to prevent
+  # accidentally adding new jobs without also updating the branch protections.
+  success:
+    name: Success gate
+    if: always()
+    needs:
+      - code-tests
+      - style-tests
+      - mdbook-spec
+      # preview is explicitly excluded here since it doesn't run on merge
+    runs-on: ubuntu-latest
+    steps:
+      - run: jq --exit-status 'all(.result == "success")' <<< '${{ toJson(needs) }}'
+      - name: Done
+        run: exit 0

CONTRIBUTING.md

@@ -14,10 +14,10 @@ for the Reference. As such, we have the warning saying there's work that needs
 to be done. Eventually, we plan to make sure everything is well documented
 enough that we can remove the warning.
 
-It is encouraged for you to read the [introduction] to familiarize yourself
-with the kind of content the reference is expected to contain and the
-conventions it uses. Also, the [style guide] provides more detailed guidelines
-for formatting and content.
+It is encouraged for you to read the [introduction] to familiarize yourself with
+the kind of content the reference is expected to contain and the conventions it
+uses. Also, the [Authoring Guide] provides more detailed guidelines for
+formatting and content.
 
 ## Critiquing the Reference
 
@@ -68,9 +68,9 @@ This should include links to any relevant information, such as the
 stabilization PR, the RFC, the tracking issue, and anything else that would be
 helpful for writing the documentation.
 
+[Authoring Guide]: docs/authoring.md
 [introduction]: src/introduction.md
 [issue tracker]: https://github.com/rust-lang/reference/issues
 [playpen]: https://play.rust-lang.org/
 [rust-lang/rust]: https://github.com/rust-lang/rust/
-[style guide]: STYLE.md
 [unstable]: https://doc.rust-lang.org/nightly/unstable-book/

README.md

@@ -1,6 +1,7 @@
 # The Rust Language Reference
 
-This document is the primary reference for the Rust programming language.
+This document is the primary reference for the Rust programming
+language.
 
 This document is not normative. It may include details that are specific
 to `rustc` itself, and should not be taken as a specification for the
@@ -9,52 +10,78 @@ what we have for now.
 
 ## Dependencies
 
-- rustc (the Rust compiler).
-- [mdbook](https://rust-lang.github.io/mdBook/) (use `cargo install mdbook` to install it).
-- rust nightly (you would be required to set your Rust version to the nightly version to make sure all tests pass)
+- Nightly Rust
+- [mdbook](https://rust-lang.github.io/mdBook/)
 
-## Build steps
+## Installing dependencies
 
-To build the project, follow the steps given below :
+First, ensure that you have a recent copy of the nightly Rust compiler
+installed, as this is needed in order to run the tests:
 
-Clone the project by downloading the ZIP from the [GitHub page](https://github.com/rust-lang/reference) or
-run the following command:
-
-```
-git clone https://github.com/rust-lang/reference
+```sh
+rustup toolchain install nightly
 ```
 
-Change the directory to the downloaded repository:
+Now, ensure you have `mdbook` installed, as this is needed in order to
+build the Reference:
 
 ```sh
-cd reference
+cargo install --locked mdbook
 ```
 
-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:
+## Building
+
+To build the Reference, first clone the project:
 
-```shell
-rustup override set nightly
+```sh
+git clone https://github.com/rust-lang/reference.git
 ```
 
-This will set the nightly version only for your the current project.
+(Alternatively, if you don't want to use `git`, [download][] a ZIP file
+of the project, extract it using your preferred tool, and rename the
+top-level directory to `reference`.)
 
-If you wish to set Rust nightly for all your projects, you can run the command: 
+[download]: https://github.com/rust-lang/reference/archive/refs/heads/master.zip
 
-```shell
-rustup default nightly
+Now change your current directory to the working directory:
+
+```sh
+cd reference
 ```
 
-Now, run the following command to test the code snippets to catch compilation errors:
+To test all of the code examples in the Reference, run:
 
-```shell
+```sh
 mdbook test
 ```
 
+For authors, consider using the server functionality which supports automatic reload.
 
-To generate a local instance of the book, run:
+To build the Reference locally (in `build/`) and open it in a web
+browser, run:
 
 ```sh
-mdbook build
+SPEC_RELATIVE=0 mdbook build --open
 ```
 
-The generated HTML will be in the `book` folder.
+This will open a browser with a websocket live-link to automatically reload whenever the source is updated.
+
+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:
+
+```sh
+SPEC_RELATIVE=0 mdbook serve --open
+```
+
+### `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.
+
+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`
+
+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.
+
+### `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.

STYLE.md

@@ -1,71 +1,5 @@
 # Rust reference style guide
 
-Some conventions and content guidelines are specified in the [introduction].
-This document serves as a guide for editors and reviewers.
+See the [Authoring Guide] for details on the style used in the reference.
 
-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`.
-
-## Markdown formatting
-
-* Use ATX-style heading with sentence case.
-* Use one line per sentence to make diffs nicer.
-  Do not wrap long lines.
-* Use reference links, with shortcuts if appropriate.
-  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.
-
-    ```
-    Example of shortcut link: [enumerations]
-    Example of reference link with label: [block expression][block]
-
-    [block]: expressions/block-expr.md
-    [enumerations]: types/enum.md
-    ```
-
-* Links should be relative with the `.md` extension.
-  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.
-* See the [Conventions] section for formatting callouts such as notes, edition differences, and warnings.
-* Formatting to avoid:
-    * Avoid trailing spaces.
-    * Avoid double blank lines.
-
-### Code examples
-
-Code examples should use code blocks with triple backticks.
-The language should always be specified (such as `rust`).
-
-```rust
-println!("Hello!");
-```
-
-See https://highlightjs.org/ for a list of supported languages.
-
-Rust examples are tested via rustdoc, and should include the appropriate annotations when tests are expected to fail:
-
-* `edition2015` or `edition2018` — If it is edition-specific (see `book.toml` for the default).
-* `no_run` — The example should compile successfully, but should not be executed.
-* `should_panic` — The example should compile and run, but produce a panic.
-* `compile_fail` — The example is expected to fail to compile.
-* `ignore` — The example shouldn't be built or tested.
-  This should be avoided if possible.
-  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.
-  An HTML comment such as `<!-- ignore: requires extern crate -->` should be placed before the example to explain why it is ignored.
-
-See the [rustdoc documentation] for more detail.
-
-## Language and grammar
-
-* Use American English spelling.
-* Use Oxford commas.
-* Idioms and styling to avoid:
-    * Avoid slashes for alternatives ("program/binary"), use conjunctions or rewrite it ("program or binary").
-    * Avoid qualifying something as "in Rust", the entire reference is about Rust.
-
-## Content
-
-* Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block.
-  The main text should stick to what is common between the editions.
-  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.
-
-[conventions]: src/introduction.md#conventions
-[introduction]: src/introduction.md
-[rustdoc documentation]: https://doc.rust-lang.org/rustdoc/documentation-tests.html
+[Authoring Guide]: docs/authoring.md

book.toml

@@ -5,13 +5,21 @@ author = "The Rust Project Developers"
 
 [output.html]
 additional-css = ["theme/reference.css"]
+additional-js = ["theme/reference.js"]
 git-repository-url = "https://github.com/rust-lang/reference/"
 edit-url-template = "https://github.com/rust-lang/reference/edit/master/{path}"
+smart-punctuation = true
 
 [output.html.redirect]
 "/expressions/enum-variant-expr.html" = "struct-expr.html"
 "/unsafe-blocks.html" = "unsafe-keyword.html"
 "/unsafe-functions.html" = "unsafe-keyword.html"
 
 [rust]
-edition = "2021"
+edition = "2024"
+
+[preprocessor.spec]
+command = "cargo run --release --manifest-path mdbook-spec/Cargo.toml"
+
+[build]
+extra-watch-dirs = ["mdbook-spec/src"]