diff --git a/.github/workflows/docs-lint.yml b/.github/workflows/docs-lint.yml new file mode 100644 index 0000000000..1cae9f27de --- /dev/null +++ b/.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 ~15s, but saves us minutes of build. + - name: Load rust cache + uses: astriaorg/buildjet-rust-cache@v2.5.1 + + # Building with warm cache takes ~40s, 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/buildjet-rust-cache@v2.5.1 + + # 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 diff --git a/.github/workflows/notes.yml b/.github/workflows/notes.yml index 86fc79a661..8a1b660575 100644 --- a/.github/workflows/notes.yml +++ b/.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 diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index 2656fcffdb..9d1dff519f 100644 --- a/.github/workflows/rust.yml +++ b/.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/buildjet-rust-cache@v2.5.1 - 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/buildjet-rust-cache@v2.5.1 - - name: Build rustdocs - run: ./deployments/scripts/rust-docs \ No newline at end of file diff --git a/docs/guide/book.toml b/docs/guide/book.toml index f2652f8691..3557436510 100644 --- a/docs/guide/book.toml +++ b/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'] diff --git a/docs/protocol/book.toml b/docs/protocol/book.toml index ae8d613773..9b1d98ba59 100644 --- a/docs/protocol/book.toml +++ b/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']