Merge branch 'master' into spec-add-identifiers-attributes

Author: chorman0773

.github/workflows/main.yml

@@ -5,29 +5,18 @@ on:
 
 env:
   MDBOOK_VERSION: 0.4.40
-  # When updating, be sure to also update rust-lang/rust.
-  MDBOOK_SPEC_VERSION: 0.1.0
 
 jobs:
-  test:
-    name: Test
+  code-tests:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@master
-    - name: Cache
-      uses: actions/cache@v4
-      with:
-        path: |
-          ~/.cargo/bin/
-          ~/.cargo/.crates.toml
-          ~/.cargo/.crates2.json
-        key: ms-${MDBOOK_SPEC_VERSION}
     - name: Update rustup
       run: rustup self update
     - name: Install Rust
       run: |
         rustup set profile minimal
-        rustup toolchain install nightly -c rust-docs,rustfmt
+        rustup toolchain install nightly
         rustup default nightly
     - name: Install mdbook
       run: |
@@ -39,13 +28,37 @@ jobs:
         rustup --version
         rustc -Vv
         mdbook --version
-    - name: Install mdbook-spec
-      run: cargo install --locked mdbook-spec@${MDBOOK_SPEC_VERSION}
     - name: Run tests
       run: mdbook test
+
+  style-tests:
+    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 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: Verify the book builds
+      env:
+        SPEC_DENY_WARNINGS: 1
+      run: mdbook build
     - name: Style checks
       working-directory: style-check
-      run: cargo run -- ../src
+      run: cargo run --locked -- ../src
     - name: Style fmt
       working-directory: style-check
       run: cargo fmt --check
@@ -54,3 +67,51 @@ jobs:
         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
+
+  # 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
+    runs-on: ubuntu-latest
+    steps:
+      - run: jq --exit-status 'all(.result == "success")' <<< '${{ toJson(needs) }}'
+      - name: Done
+        run: exit 0

README.md

@@ -12,7 +12,6 @@ what we have for now.
 
 - Nightly Rust
 - [mdbook](https://rust-lang.github.io/mdBook/)
-- [`mdbook-spec`](https://github.com/rust-lang/spec/tree/main/mdbook-spec)
 
 ## Installing dependencies
 
@@ -30,12 +29,6 @@ build the Reference:
 cargo install --locked mdbook
 ```
 
-Also install `mdbook-spec` which is a preprocessor which adds some Markdown extensions:
-
-```sh
-cargo install --locked mdbook-spec
-```
-
 ## Building
 
 To build the Reference, first clone the project:
@@ -68,15 +61,15 @@ 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:
+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.
+
+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
 ```
-
-

book.toml

@@ -18,3 +18,7 @@ smart-punctuation = true
 edition = "2021"
 
 [preprocessor.spec]
+command = "cargo run --release --manifest-path mdbook-spec/Cargo.toml"
+
+[build]
+extra-watch-dirs = ["mdbook-spec/src"]

docs/authoring.md

@@ -109,6 +109,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 +154,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/.gitignore

@@ -0,0 +1 @@
+/target

mdbook-spec/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## mdbook-spec 0.1.2
+
+- Fixed some issues with rust-lang/rust build integration.
+
+## mdbook-spec 0.1.1
+
+- Moved code to a library to support upstream integration.
+
+## mdbook-spec 0.1.0
+
+- Initial release