rustc-dev-guide subtree update

src/doc/rustc-dev-guide/.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       BASE_SHA: ${{ github.event.pull_request.base.sha }}
       GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v7
         with:
           # linkcheck needs the base commit.
           fetch-depth: 0
@@ -54,13 +54,19 @@ jobs:
       - name: Install Dependencies
         if: steps.mdbook-cache.outputs.cache-hit != 'true'
         run: |
-          cargo install mdbook --version ${{ env.MDBOOK_VERSION }}
-          cargo install mdbook-linkcheck2 --version ${{ env.MDBOOK_LINKCHECK2_VERSION }}
-          cargo install mdbook-mermaid --version ${{ env.MDBOOK_MERMAID_VERSION }}
+          cargo install --locked mdbook --version ${{ env.MDBOOK_VERSION }}
+          cargo install --locked mdbook-linkcheck2 --version ${{ env.MDBOOK_LINKCHECK2_VERSION }}
+          cargo install --locked mdbook-mermaid --version ${{ env.MDBOOK_MERMAID_VERSION }}
 
       - name: Check build
         run: ENABLE_LINKCHECK=1 mdbook build
 
+      - name: Check build with link checking disabled
+        run: |
+          output=$(mktemp)
+          mdbook build 2>&1 | tee "$output"
+          ! grep -F "Broken pipe" "$output"
+
       - name: Save cached Linkcheck
         id: cache-linkcheck-save
         if: ${{ !cancelled() && github.event_name == 'schedule' }}

src/doc/rustc-dev-guide/.github/workflows/date-check.yml

@@ -15,7 +15,7 @@ jobs:
 
     steps:
       - name: Checkout repo
-        uses: actions/checkout@v5
+        uses: actions/checkout@v7
 
       - name: Ensure Rust is up-to-date
         run: |

src/doc/rustc-dev-guide/README.md

@@ -1,19 +1,18 @@
 [![CI](https://github.com/rust-lang/rustc-dev-guide/actions/workflows/ci.yml/badge.svg)](https://github.com/rust-lang/rustc-dev-guide/actions/workflows/ci.yml)
 
+## About the `rustc-dev-guide`
+
 This is a collaborative effort to build a guide that explains how rustc works.
 The aim of the guide is to help new contributors get oriented to rustc,
 as well as to help more experienced folks in figuring out
 some new part of the compiler that they haven't worked on before.
 
-You may also find the [rustc API docs] useful.
-
-Note that these are not intended as a guide; it's recommended that you search
-for the docs you're looking for instead of reading them top to bottom.
+For more information, see [About This Guide](./src/about-this-guide.md).
 
 For documentation on developing the standard library, see
 [`std-dev-guide`](https://std-dev-guide.rust-lang.org/).
 
-### Contributing to the guide
+## Contributing to the guide
 
 The guide is useful today, but it has a lot of work still to go.
 
@@ -24,35 +23,28 @@ Just post a comment on the issue you would like to work on to make sure that we
 accidentally duplicate work.
 If you think something is missing, please open an issue about it!
 
-**In general, if you don't know how the compiler works, that is not a
-problem!** In that case, what we will do is to schedule a bit of time
-for you to talk with someone who **does** know the code, or who wants
-to pair with you and figure it out.
-Then you can work on writing up what you learned.
-
-In general, when writing about a particular part of the compiler's code, we
-recommend that you link to the relevant parts of the [rustc API docs].
+See below for instructions on [writing new docs](#editing-the-guide).
 
 The guide has a much lower bar for what it takes for a PR to be merged.
 Check out the forge documentation for [our policy][forge_policy].
 
 [forge_policy]: https://forge.rust-lang.org/rustc-dev-guide/index.html#review-policy
 
-### Build Instructions
+## Build Instructions
 
 To build a local static HTML site, install [`mdbook`](https://github.com/rust-lang/mdBook) with:
 
 ```
-cargo install mdbook mdbook-linkcheck2 mdbook-mermaid
+cargo install --locked mdbook mdbook-linkcheck2 mdbook-mermaid
 ```
 
 and execute the following command in the root of the repository:
 
 ```
-mdbook build --open
+mdbook serve --open
 ```
 
-The build files are found in the `book/html` directory.
+For a one-off build, you can use `mdbook build`.
 
 ### Link Validations
 
@@ -65,11 +57,46 @@ following example.
 ENABLE_LINKCHECK=1 mdbook serve
 ```
 
-## Synchronizing josh subtree with rustc
+## Editing the guide
+
+### Where to start
+
+**In general, if you don't know how the compiler works, that is not a
+problem!** In that case, what we will do is to schedule a bit of time
+for you to talk with someone who **does** know the code, or who wants
+to pair with you and figure it out.
+Then you can work on writing up what you learned.
+
+### Layout
+
+The dev-guide is organized as a normal [mdBook](https://rust-lang.github.io/mdBook/):
+It has a `src/SUMMARY.md` table of contents, which links to individual pages under `src/`.
+Configuration lives in `book.toml`.
+Images are in `src/img`.
+The build files are found in the `book/html` directory.
+
+**NOTE: if you do not add a page to SUMMARY.md, it will not be shown!**
+
+### While writing
+
+See the guide itself for instructions on [writing new docs].
+
+[writing new docs]: src/contributing-to-guide.md
+
+## Maintaining the guide
+
+### CI
+
+Various tools are kept under `ci/`.
+Check links with `mdbook-linkcheck2 --standalone`.
+Check semantic line breaks with `cargo run --manifest-path ci/sembr/Cargo.toml src`.
+Triage `<!-- date-check -->` annotations with `cargo run --manifest-path ci/date-check/Cargo.toml .`.
+
+You can test those tools with `cargo test --manifest-path ci/<tool>/Cargo.toml`.
+
+### Synchronizing josh subtree with rustc
 
 This repository is linked to `rust-lang/rust` as a [josh](https://josh-project.github.io/josh/intro.html) subtree.
 You can use the [rustc-josh-sync](https://github.com/rust-lang/josh-sync) tool to perform synchronization.
 
 You can find a guide on how to perform the synchronization [here](./src/external-repos.md#synchronizing-a-josh-subtree).
-
-[rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle

src/doc/rustc-dev-guide/book.toml

@@ -96,3 +96,4 @@ warning-policy = "error"
 "/ty_module/instantiating_binders.html" = "/ty-module/instantiating-binders.html"
 "/ty_module/param_ty_const_regions.html" = "/ty-module/param-ty-const-regions.html"
 "/typing_parameter_envs.html" = "typing-parameter-envs.html"
+"/walkthrough.html" = "walkthroughs/test.html"

src/doc/rustc-dev-guide/ci/linkcheck.sh

@@ -11,6 +11,9 @@ set_github_token() {
 
 if [ -z "$ENABLE_LINKCHECK" ] ; then
   echo "Skipping link check."
+  # mdBook writes the render context to extensions over stdin.
+  # Discard it so mdBook doesn't warn about a broken pipe.
+  cat > /dev/null
   exit 0
 fi