latest version

.github/workflows/main.yml

@@ -35,6 +35,11 @@ jobs:
     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
@@ -52,16 +57,17 @@ jobs:
         rustup --version
         rustc -Vv
         mdbook --version
-    - name: Verify the book builds
-      env:
-        SPEC_DENY_WARNINGS: 1
-      run: mdbook build
     - name: Style checks
       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 \
@@ -98,6 +104,40 @@ jobs:
       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
@@ -110,6 +150,7 @@ jobs:
       - 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) }}'

README.md

@@ -61,13 +61,27 @@ To build the Reference locally (in `build/`) and open it in a web
 browser, run:
 
 ```sh
-mdbook build --open
+SPEC_RELATIVE=0 mdbook build --open
 ```
 
 This will open a browser with a websocket live-link to automatically reload whenever the source is updated.
 
-You can also open any current build of the reference by running:
+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
-mdbook serve --open
+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.

book.toml

@@ -5,6 +5,7 @@ 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
@@ -18,7 +19,7 @@ smart-punctuation = true
 edition = "2021"
 
 [preprocessor.spec]
-command = "cargo run --manifest-path mdbook-spec/Cargo.toml"
+command = "cargo run --release --manifest-path mdbook-spec/Cargo.toml"
 
 [build]
 extra-watch-dirs = ["mdbook-spec/src"]

docs/authoring.md

@@ -15,7 +15,8 @@ This document serves as a guide for editors and reviewers. Some conventions and
 * Code blocks should have an explicit language tag.
 * Do not wrap long lines. This helps with reviewing diffs of the source.
 * Use [smart punctuation] instead of Unicode characters. For example, use `---` for em-dash instead of the Unicode character. Characters like em-dash can be difficult to see in a fixed-width editor, and some editors may not have easy methods to enter such characters.
-* 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.
+* Links should be relative with the `.md` extension. Links to other rust-lang books that are published with the reference should also be relative so that the linkchecker can validate them.
+* Links to the standard library should use rustdoc-style links described in [Standard library links](#standard-library-links).
 * The use of reference links is preferred, 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 are an unusually large number of links that are specific to the section.
 
     ```markdown
@@ -75,6 +76,45 @@ Rules can be linked to by their ID using markdown such as `[foo.bar]`. There are
 
 In the HTML, the rules are clickable just like headers.
 
+When assigning rules to new paragraphs, or when modifying rule names, use the following guidelines:
+
+1. A rule applies to one core idea, which should be easily determined when reading the paragraph it is applied to.
+2. Other than the "intro" paragraph, purely explanatory, expository, or exemplary content does not need a rule. If the expository paragraph isn't directly related to the previous, separate it with a hard (rendered) line break.
+    * This content will be moved to `[!NOTE]` or more specific admonitions in the future.
+3. Rust code examples and tests do not need their own rules.
+4. Use the following guidelines for admonitions:
+    * Notes: Do not include a rule.
+    * Warning: Omit the rule if the warning follows from the previous paragraph or if the warning is explanatory and doesn't introduce any new rules.
+    * Target specific behavior: Always include the rule.
+    * Edition differences: Always include the rule.
+5. The following keywords should be used to identify paragraphs when unambiguous:
+    * `intro`: The beginning paragraph of each section - should explain the construct being defined overall.
+    * `syntax`: Syntax definitions or explanations when BNF syntax definitions are not used.
+    * `namespace`: For items only, specifies the namespace(s) the item introduces a name in. May also be used elsewhere when defining a namespace (e.g. `r[attribute.diagnostic.namespace]`).
+6. When a rule doesn't fall under the above keywords, or for section rule ids, name the subrule as follows:
+    * If the rule is naming a specific Rust language construct (e.g. an attribute, standard library type/function, or keyword-introduced concept), use the construct as named in the language, appropriately case-adjusted (but do not replace `_`s with `-`s).
+    * Other than Rust language concepts with `_`s in the name, use `-` characters to separate words within a "subrule".
+    * Whenever possible, do not repeat previous components of the rule.
+    * Edition differences admonitions should typically be named by the edition referenced directly by the rule. If multiple editions are named, use the one for which the behavior is defined by the admonition, and not by a previous paragraph.
+    * Target specific admonitions should typically be named by the least specific target property to which they apply (e.g. if a rule affects all x86 CPUs, the rule name should include `x86` rather than separately listing `i586`, `i686` and `x86_64`, and if a rule applies to all ELF platforms, it should be named `elf` rather than listing every ELF OS).
+    * Use an appropriately descriptive, but short, name if the language does not provide one.
+
+#### Test rule annotations
+
+Tests in <https://github.com/rust-lang/rust> can be linked to rules in the reference. The rule will include a link to the tests, and there is also an [appendix] which tracks how the rules are currently linked.
+
+Tests in the `tests` directory can be annotated with the `//@ reference: x.y.z` header to link it to a rule. The header can be specified multiple times if a single file covers multiple rules.
+
+Compiler developers are not expected to add `reference` annotations to tests. However, if they do want to help, their cooperation is very welcome. Reference authors and editors are responsible for making sure every rule has a test associated with it.
+
+The tests are beneficial for reviewers to see the behavior of a rule. It is also a benefit to readers who may want to see examples of particular behaviors. When adding new rules, you should wait until the reference side is approved before submitting a PR to `rust-lang/rust` (to avoid churn if we decide on different names).
+
+Prefixed rule names should not be used in tests. That is, do not use something like `asm.rules` when there are specific rules like `asm.rules.reg-not-input`.
+
+We are not expecting 100% coverage at any time. Although it would be nice, it is unrealistic due to the sequence things are developed, and resources available.
+
+[appendix]: https://doc.rust-lang.org/nightly/reference/test-summary.html
+
 ### Standard library links
 
 You should link to the standard library without specifying a URL in a fashion similar to [rustdoc intra-doc links][intra]. Some examples:
@@ -109,6 +149,15 @@ Explicit namespace disambiguation is also supported:
 [`std::vec`](mod@std::vec)
 ```
 
+Beware there are some limitations, for example:
+
+- Links to rexports from `std_arch` don't work due to <https://github.com/rust-lang/rust/issues/96506>.
+- Links to keywords aren't supported.
+- Links to trait impls where the trait is not in the prelude doesn't work. Traits must be in scope, and there currently isn't a way to add those.
+- If there are multiple generic implementations, it will link to one randomly (see <https://github.com/rust-lang/rust/issues/76895>).
+
+When running into a rustdoc limitation, consider manually linking to the correct page using a relative link. For example, `../std/arch/macro.is_x86_feature_detected.html`.
+
 [intra]: https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html
 
 ### Admonitions
@@ -145,4 +194,4 @@ The reference does not document which targets exist, or the properties of specif
 
 ### Editions
 
-The main text and flow should document only the current edition. Whenever there is a difference between editions, the differences should be called out with an "Edition Differences" block.
+The main text and flow should document only the current edition. Whenever there is a difference between editions, the differences should be called out with an "Edition differences" block.

mdbook-spec/Cargo.toml

@@ -13,7 +13,10 @@ anyhow = "1.0.79"
 mdbook = { version = "0.4.36", default-features = false }
 once_cell = "1.19.0"
 pathdiff = "0.2.1"
+# Try to keep in sync with mdbook.
+pulldown-cmark = { version = "0.10.3", default-features = false }
 regex = "1.9.4"
 semver = "1.0.21"
 serde_json = "1.0.113"
 tempfile = "3.10.1"
+walkdir = "2.5.0"