ci: use mdbook-linkcheck for docs linting

Runs `mdbook-linkcheck` [0] on PRs, ensuring that docs are checked for
broken links prior to merge. We don't want to slow down per-PR CI runs,
so it's important these steps run in parallel, from a warm cache.
The cargo test workflow takes ~5m, so as long as we're under that,
we should be good.

There's another subtle change in here: we reduce the number of CI vCPUs
dedicated to these docs-building jobs, ensuring there's more compute
available for the CPU-intensive jobs like cargo test. This allows more
CI runs in parallel as multiple PRs are modified concurrently. Overall,
the per-PR CPU reservation has changed from 80 -> 68. After observing
the effect on CI runtimes, I suspect we can finetune further, and even
bump up cargo test up to a 32-cpu runner if we gain back enough
headroom.

Refs #3994, which recommended the use of mdbook-linkcheck.

[0] https://github.com/Michael-F-Bryan/mdbook-linkcheck

.github/workflows/docs-lint.yml

@@ -0,0 +1,54 @@
+name: Docs lint
+on: pull_request
+
+jobs:
+  rustdocs:
+    # We use a custom script to generate the index page for https://rustdoc.penumbra.zone,
+    # and refactors to rust deps can break that generation. Let's ensure this script exits 0
+    # on PRs, but we'll still only deploy after merge into main.
+    name: rustdoc-lint
+    runs-on: buildjet-8vcpu-ubuntu-2204
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: false
+
+      - name: Install rust toolchain
+        # The script for rustdoc build requires nightly toolchain.
+        uses: dtolnay/rust-toolchain@nightly
+
+      # Loading cache takes ~XXs, but saves us minutes of build.
+      - name: Load rust cache
+        uses: astriaorg/[email protected]
+
+      # Building with warm cache takes ~XXs, depending on changes.
+      - name: Build rustdocs
+        run: ./deployments/scripts/rust-docs
+
+  # Also validate that the `mdbook` docs (guide & protocol) build correctly.
+  # In particular, links are checked within the docs.
+  mdbook:
+    name: mdbook-lint
+    # Downgrading runner size to 4vcpu, since we're not compiling code.
+    runs-on: buildjet-4vcpu-ubuntu-2204
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          lfs: false
+
+      - name: Install rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Load rust cache
+        uses: astriaorg/[email protected]
+
+      # It's OK to install from crates, building from source, because of cache use
+      # on previous step. Install takes ~5s with warm cache.
+      - name: Install mdbook dependencies
+        run: cargo install mdbook mdbook-katex mdbook-mermaid mdbook-linkcheck
+
+      - name: Build guide docs
+        run: cd docs/guide && mdbook build
+
+      - name: Build protocol docs
+        run: cd docs/protocol && mdbook build

.github/workflows/notes.yml

@@ -26,8 +26,11 @@ jobs:
         id: get_version
       - name: Print version component of deployment path
         run: echo ${{ steps.get_version.outputs.version }}
-      - name: Install mdbook
-        run: cargo install mdbook mdbook-katex mdbook-mermaid
+
+      # Ostensibly building from source, but the cache-loading above
+      # ensures we don't need to rebuild frequently.
+      - name: Install mdbook dependencies
+        run: cargo install mdbook mdbook-katex mdbook-mermaid mdbook-linkcheck
 
       - name: Build software guide
         run: cd docs/guide && mdbook build

.github/workflows/rust.yml

@@ -42,7 +42,7 @@ jobs:
 
   fmt:
     name: Rustfmt
-    runs-on: buildjet-16vcpu-ubuntu-2204
+    runs-on: buildjet-8vcpu-ubuntu-2204
     steps:
       - uses: actions/checkout@v4
       - name: Install rust toolchain
@@ -52,21 +52,3 @@ jobs:
       - name: Load rust cache
         uses: astriaorg/[email protected]
       - run: cargo fmt --all -- --check
-
-  docs:
-    # We use a custom script to generate the index page for https://rustdoc.penumbra.zone,
-    # and refactors to rust deps can break that generation. Let's ensure this script exits 0
-    # on PRs, but we'll still only deploy after merge into main.
-    name: Check that rustdocs build OK
-    runs-on: buildjet-16vcpu-ubuntu-2204
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          lfs: true
-      - name: Install rust toolchain
-        # The script for rustdoc build requires nightly toolchain.
-        uses: dtolnay/rust-toolchain@nightly
-      - name: Load rust cache
-        uses: astriaorg/[email protected]
-      - name: Build rustdocs
-        run: ./deployments/scripts/rust-docs

docs/guide/book.toml

@@ -19,11 +19,11 @@ fold = { enable = true, level = 1 }
 git-repository-url = "https://github.com/penumbra-zone/penumbra"
 additional-js =["theme/js/mermaid.min.js", "theme/js/mermaid-init.js"]
 
-# Documenting config for `mdbook-linkcheck`. We don't have this
-# enabled in CI yet, but it's sure handy for fixing up links.
-# [output.linkcheck]
-# follow-web-links = false
-# warning-policy = "ignore"
-#
+[output.linkcheck]
+# Consider setting `follow-web-links=true` ad-hoc, to validate external URLs.
+follow-web-links = false
+warning-policy = "ignore"
+
 # The buf.build website doesn't support HTTP HEAD calls, returning 405.
-# exclude = ['buf\.build']
+# Only relevant when `follow-web-links=true`.
+exclude = ['buf\.build']

docs/protocol/book.toml

@@ -18,8 +18,11 @@ fold = { enable = true, level = 1 }
 git-repository-url = "https://github.com/penumbra-zone/penumbra"
 additional-js =["theme/js/mermaid.min.js", "theme/js/mermaid-init.js"]
 
-# Documenting config for `mdbook-linkcheck`. We don't have this
-# enabled in CI yet, but it's sure handy for fixing up links.
-# [output.linkcheck]
-# follow-web-links = false
-# warning-policy = "ignore"
+[output.linkcheck]
+# Consider setting `follow-web-links=true` ad-hoc, to validate external URLs.
+follow-web-links = false
+warning-policy = "ignore"
+
+# The buf.build website doesn't support HTTP HEAD calls, returning 405.
+# Only relevant when `follow-web-links=true`.
+exclude = ['buf\.build']