documenteer 2.5.0b2__tar.gz → 2.5.0b4__tar.gz

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/.agents/skills/project-mechanics/SKILL.md

@@ -12,7 +12,7 @@ of each phase and use the named commands verbatim.
 Tasks run through nox (via nox-uv). Invoke nox through uv so the runner
 group is provisioned automatically: `uv run --only-group=nox nox ...`.
 The `test`, `typing`, and `demo` sessions are parametrized over both
-Python (3.12, 3.13) and Sphinx (8, 9, dev), so their session IDs carry
+Python (3.12 through 3.15) and Sphinx (8, 9, dev), so their session IDs carry
 both factors, e.g. `test-3.13(sphinx='8')`. uv furnishes the requested
 interpreter on demand. Run `nox -l` to confirm the exact IDs.
 
@@ -40,6 +40,15 @@ per-invocation combine and upload raw `.coverage.*` data for a central
 - `lint_touched`: `uv run --only-group=lint prek run --files {files}`
 - `lint_all`: `uv run --only-group=nox nox -s lint`
 
+## Prose (optional)
+
+- `vale`: `uv run --only-group=nox nox -s vale -- <docs paths>` runs Vale
+  (Google style + house rules) over documentation prose. Advisory only: it
+  is **not** part of final validation, never fails, and has no prek hook.
+  Use it for feedback when editing pages under `docs/`; add legitimate terms
+  to `styles/config/vocabularies/Documenteer/accept.txt`, fix real typos in
+  the source.
+
 ## Typing
 
 - `typing`: `uv run --only-group=nox nox -s "typing-3.13(sphinx='8')"`
@@ -54,7 +63,7 @@ order, in the foreground, plus `uv run --only-group=nox nox -s
 and `uv run --only-group=nox nox -s docs` (Documenteer's own Sphinx docs
 build).
 
-The full Python × Sphinx matrix (3.12/3.13 × Sphinx 8/9), `nox -s
+The full Python × Sphinx matrix (3.12-3.15 × Sphinx 8/9), `nox -s
 docs-linkcheck` (linkcheck), and `nox -s packaging` (build + twine
 check) are CI's responsibility, not the in-iteration gate.
 

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/.claude/skills/project-mechanics/SKILL.md

@@ -12,7 +12,7 @@ of each phase and use the named commands verbatim.
 Tasks run through nox (via nox-uv). Invoke nox through uv so the runner
 group is provisioned automatically: `uv run --only-group=nox nox ...`.
 The `test`, `typing`, and `demo` sessions are parametrized over both
-Python (3.12, 3.13) and Sphinx (8, 9, dev), so their session IDs carry
+Python (3.12 through 3.15) and Sphinx (8, 9, dev), so their session IDs carry
 both factors, e.g. `test-3.13(sphinx='8')`. uv furnishes the requested
 interpreter on demand. Run `nox -l` to confirm the exact IDs.
 
@@ -40,6 +40,15 @@ per-invocation combine and upload raw `.coverage.*` data for a central
 - `lint_touched`: `uv run --only-group=lint prek run --files {files}`
 - `lint_all`: `uv run --only-group=nox nox -s lint`
 
+## Prose (optional)
+
+- `vale`: `uv run --only-group=nox nox -s vale -- <docs paths>` runs Vale
+  (Google style + house rules) over documentation prose. Advisory only: it
+  is **not** part of final validation, never fails, and has no prek hook.
+  Use it for feedback when editing pages under `docs/`; add legitimate terms
+  to `styles/config/vocabularies/Documenteer/accept.txt`, fix real typos in
+  the source.
+
 ## Typing
 
 - `typing`: `uv run --only-group=nox nox -s "typing-3.13(sphinx='8')"`
@@ -54,7 +63,7 @@ order, in the foreground, plus `uv run --only-group=nox nox -s
 and `uv run --only-group=nox nox -s docs` (Documenteer's own Sphinx docs
 build).
 
-The full Python × Sphinx matrix (3.12/3.13 × Sphinx 8/9), `nox -s
+The full Python × Sphinx matrix (3.12-3.15 × Sphinx 8/9), `nox -s
 docs-linkcheck` (linkcheck), and `nox -s packaging` (build + twine
 check) are CI's responsibility, not the in-iteration gate.
 

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/.devcontainer/Dockerfile

@@ -1,5 +1,6 @@
 # Project dev container for documenteer.
-# A minimal Python 3.13 base plus uv and the system packages the build needs.
+# A minimal Python base (matching .python-version) plus uv and the system
+# packages the build needs.
 # Kept project-only and COPY-free so a local build and the stoker-derived
 # sandbox build are identical.
 FROM mcr.microsoft.com/devcontainers/python:1-3.13-bookworm

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/.github/workflows/ci-cron.yaml

@@ -4,9 +4,6 @@
 
 name: Periodic CI
 
-env:
-  PYTHON_VERSION: "3.13"
-
 "on":
   schedule:
     - cron: "0 12 * * 1"
@@ -35,12 +32,12 @@ jobs:
           npm run build
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v9.0.0
+        uses: astral-sh/setup-uv@v10.3.0
 
+      # uv reads the canonical Python version from .python-version, so nox and
+      # its unparametrized sessions (lint, docs, ...) run on that interpreter.
       - name: Run nox
-        run: uv run --only-group=nox nox -P $UV_PYTHON -s lint
-        env:
-          UV_PYTHON: ${{ env.PYTHON_VERSION }}
+        run: uv run --only-group=nox nox -s lint
 
       - name: Report status
         if: failure()
@@ -61,6 +58,7 @@ jobs:
           - "3.12"
           - "3.13"
           - "3.14"
+          - "3.15"
         sphinx-version:
           - "8"
           - "9"
@@ -90,7 +88,13 @@ jobs:
         uses: ts-graphviz/setup-graphviz@v2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v9.0.0
+        uses: astral-sh/setup-uv@v10.3.0
+
+      # The canonical development Python (.python-version) identifies the
+      # matrix cells that upload the demo builds below.
+      - name: Read the canonical Python version
+        id: python
+        run: echo "version=$(cat .python-version)" >> "$GITHUB_OUTPUT"
 
       - name: Run nox
         run: >
@@ -104,7 +108,7 @@ jobs:
       # Guarded so partial/missing HTML (sphinx-build runs with --keep-going)
       # under `if: always()` never hard-fails the job.
       - name: Stage demo builds for upload
-        if: always() && matrix.python-version == env.PYTHON_VERSION && (matrix.sphinx-version == '9' || matrix.sphinx-version == 'dev')
+        if: always() && matrix.python-version == steps.python.outputs.version && (matrix.sphinx-version == '9' || matrix.sphinx-version == 'dev')
         run: |
           for d in rst-technote md-technote ipynb-technote; do
             if [ -d "demo/$d/_build/html" ]; then
@@ -119,7 +123,7 @@ jobs:
       # build breaks. NOTE: bump the stable sphinx-version check when the
       # matrix's current stable Sphinx moves past '9'.
       - name: Upload demo builds
-        if: always() && matrix.python-version == env.PYTHON_VERSION && (matrix.sphinx-version == '9' || matrix.sphinx-version == 'dev')
+        if: always() && matrix.python-version == steps.python.outputs.version && (matrix.sphinx-version == '9' || matrix.sphinx-version == 'dev')
         uses: actions/upload-artifact@v7
         with:
           name: demo-technotes-sphinx${{ matrix.sphinx-version }}
@@ -165,12 +169,12 @@ jobs:
         uses: ts-graphviz/setup-graphviz@v2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v9.0.0
+        uses: astral-sh/setup-uv@v10.3.0
 
       - name: Run nox
-        run: uv run --only-group=nox nox -P $UV_PYTHON -s docs docs-linkcheck
+        run: uv run --only-group=nox nox -s docs docs-linkcheck
         env:
-          UV_PYTHON: ${{ env.PYTHON_VERSION }}
+          OOK_TOKEN: ${{ secrets.OOK_TOKEN }}
 
       - name: Report status
         if: failure()
@@ -182,6 +186,30 @@ jobs:
         env:
           SLACK_WEBHOOK_URL: ${{ secrets.SLACK_ALERT_WEBHOOK }}
 
+  # Weekly whole-corpus Vale snapshot (advisory prose linting; see
+  # docs/dev/vale.rst). The nox session tolerates Vale's "findings" exit
+  # code, so this job cannot fail on prose and has no Slack notification;
+  # the report is uploaded as an artifact for review.
+  vale-report:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.0
+
+      - name: Run Vale over the documentation
+        run: uv run --only-group=nox nox -s vale | tee vale-report.txt
+
+      - name: Upload Vale report
+        uses: actions/upload-artifact@v7
+        with:
+          name: vale-report
+          path: vale-report.txt
+          if-no-files-found: warn
+          retention-days: 60
+
   pypi:
     runs-on: ubuntu-latest
 

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/.github/workflows/ci.yaml

@@ -1,8 +1,5 @@
 name: CI
 
-env:
-  PYTHON_VERSION: '3.13' # Default Python version
-
 'on':
   push:
     branches-ignore:
@@ -41,12 +38,12 @@ jobs:
           npm run build
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v9.0.0
+        uses: astral-sh/setup-uv@v10.3.0
 
+      # uv reads the canonical Python version from .python-version, so nox and
+      # its unparametrized sessions (lint, docs, ...) run on that interpreter.
       - name: Run nox
-        run: uv run --only-group=nox nox -P $UV_PYTHON -s lint
-        env:
-          UV_PYTHON: ${{ env.PYTHON_VERSION }}
+        run: uv run --only-group=nox nox -s lint
 
   test:
     runs-on: ubuntu-latest
@@ -57,6 +54,7 @@ jobs:
           - '3.12'
           - '3.13'
           - '3.14'
+          - '3.15'
         sphinx-version:
           - '8'
           - '9'
@@ -86,7 +84,13 @@ jobs:
         uses: ts-graphviz/setup-graphviz@v2
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v9.0.0
+        uses: astral-sh/setup-uv@v10.3.0
+
+      # The canonical development Python (.python-version) identifies the
+      # matrix cell that uploads the demo builds below.
+      - name: Read the canonical Python version
+        id: python
+        run: echo "version=$(cat .python-version)" >> "$GITHUB_OUTPUT"
 
       - name: Run nox
         run: >
@@ -112,7 +116,7 @@ jobs:
       # Guarded so partial/missing HTML (sphinx-build runs with --keep-going)
       # under `if: always()` never hard-fails the job.
       - name: Stage demo builds for upload
-        if: always() && matrix.python-version == env.PYTHON_VERSION && matrix.sphinx-version == '9'
+        if: always() && matrix.python-version == steps.python.outputs.version && matrix.sphinx-version == '9'
         run: |
           for d in rst-technote md-technote ipynb-technote; do
             if [ -d "demo/$d/_build/html" ]; then
@@ -122,11 +126,12 @@ jobs:
           done
 
       # Upload the rendered demo technotes for review from the Actions UI.
-      # Only the canonical cell (3.13 x current stable Sphinx) uploads, to keep
-      # the artifact list clean. NOTE: bump the sphinx-version check when the
-      # matrix's current stable Sphinx moves past '9'.
+      # Only the canonical cell (the .python-version Python x current stable
+      # Sphinx) uploads, to keep the artifact list clean. NOTE: bump the
+      # sphinx-version check when the matrix's current stable Sphinx moves
+      # past '9'.
       - name: Upload demo builds
-        if: always() && matrix.python-version == env.PYTHON_VERSION && matrix.sphinx-version == '9'
+        if: always() && matrix.python-version == steps.python.outputs.version && matrix.sphinx-version == '9'
         uses: actions/upload-artifact@v7
         with:
           name: demo-technotes-sphinx${{ matrix.sphinx-version }}
@@ -143,7 +148,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v9.0.0
+        uses: astral-sh/setup-uv@v10.3.0
 
       - name: Download coverage data
         uses: actions/download-artifact@v8
@@ -170,6 +175,31 @@ jobs:
   docs:
     runs-on: ubuntu-latest
 
+    # The link-check builder rechecks URLs Ook reports as bot-blocked from
+    # this runner's own vantage point and contributes what it observes back
+    # to the service. That contribution is attested by a GitHub Actions OIDC
+    # id token, which only exists in a job holding id-token: write. Without
+    # it the recheck still informs this build's report and the contribution
+    # is skipped with an info note.
+    #
+    # pull-requests: write lets the Docverse upload step post (and update)
+    # a comment on ticket-branch pull requests linking to the edition
+    # preview. Without it the action skips the comment with a warning.
+    permissions:
+      contents: read
+      id-token: write
+      pull-requests: write
+
+    # Link checking goes through the Ook link-check service, which needs
+    # OOK_TOKEN. Dependabot and fork pull requests don't receive repository
+    # secrets, and the extension's built-in fallback checker is too flaky
+    # from a runner against the archival hosts this guide cites (zenodo.org,
+    # datacite.org, ctan.org all timed out on dependabot docs jobs), so those
+    # runs build the docs but skip the link check. Links are still checked on
+    # every push to main and every ticket-branch pull request.
+    env:
+      HAS_OOK_TOKEN: ${{ secrets.OOK_TOKEN != '' }}
+
     steps:
       - uses: actions/checkout@v7
         with:
@@ -195,19 +225,22 @@ jobs:
           npm run build
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v9.0.0
+        uses: astral-sh/setup-uv@v10.3.0
 
-      - name: Run nox
-        run: uv run --only-group=nox nox -P $UV_PYTHON -s docs docs-linkcheck
+      - name: Build docs
+        run: uv run --only-group=nox nox -s docs
+
+      - name: Check links
+        if: env.HAS_OOK_TOKEN == 'true'
+        run: uv run --only-group=nox nox -s docs-linkcheck
         env:
-          UV_PYTHON: ${{ env.PYTHON_VERSION }}
           OOK_TOKEN: ${{ secrets.OOK_TOKEN }}
 
       # Upload the machine-readable link-check results for review from the
       # Actions UI. Runs even when docs-linkcheck fails (broken links) so the
       # JSON is available for triage; may be absent if the service degraded.
       - name: Upload link-check results
-        if: always()
+        if: always() && env.HAS_OOK_TOKEN == 'true'
         uses: actions/upload-artifact@v7
         with:
           name: linkcheck-results
@@ -215,20 +248,65 @@ jobs:
           if-no-files-found: warn
           retention-days: 7
 
-      # Only attempt documentation uploads for tagged releases and pull
-      # requests from ticket branches in the same repository.  This avoids
-      # version clutter in the docs and failures when a PR doesn't have access
-      # to secrets.
-      - name: Upload to LSST the Docs
-        uses: lsst-sqre/ltd-upload@v1
+      # Only publish for tagged releases and pull requests from ticket branches
+      # in the same repository. This avoids edition clutter and failures when a
+      # PR (fork, dependabot) doesn't have access to the DOCVERSE_TOKEN secret.
+      - name: Upload to Docverse
+        # Pinned to the pre-release head of lsst-sqre/docverse-upload; switch
+        # to a version tag once the action has an official release.
+        uses: lsst-sqre/docverse-upload@05c6698b00482673da2d1bcd93b367ebe74a98d0
         with:
-          project: 'documenteer'
-          dir: 'docs/_build/html'
-          username: ${{ secrets.LTD_USERNAME }}
-          password: ${{ secrets.LTD_PASSWORD }}
+          org: rubin
+          project: documenteer
+          dir: docs/_build/html
+          token: ${{ secrets.DOCVERSE_TOKEN }}
+          github-token: ${{ github.token }}
+          comment-on-pr: 'true'
         if: >
           github.event_name != 'pull_request' || startsWith(github.head_ref, 'tickets/')
 
+  # Advisory prose linting with Vale (https://vale.sh). This job is
+  # deliberately non-blocking and is this repo's only use of
+  # continue-on-error: vale-action runs reviewdog with fail_on_error: false
+  # and filter_mode: added, so findings surface as inline annotations on
+  # changed lines only and the job stays green even when Vale reports
+  # issues. It is intentionally absent from pypi-publish's needs. See
+  # docs/dev/vale.rst.
+  vale:
+    runs-on: ubuntu-latest
+    # Annotations are only meaningful on pull requests (reviewdog needs a diff).
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version-file: '.python-version'
+
+      # Vale shells out to rst2html (docutils) to parse reStructuredText.
+      - name: Install docutils
+        run: pip install docutils
+
+      - name: Run Vale
+        uses: errata-ai/vale-action@v3
+        # Vale is advisory: annotations should appear on the PR, but the
+        # check must stay green. fail_on_error: false covers Vale's own
+        # findings (and, since v3, GitHub's per-step annotation cap), but
+        # the step can still exit nonzero on a runtime error (download,
+        # sync, reviewdog), so tolerate any step failure outright.
+        continue-on-error: true
+        with:
+          # Match the Vale release pinned by the `vale` dependency group in
+          # uv.lock so local `nox -s vale` runs and CI agree.
+          version: 3.22.0
+          # vale-action runs `vale sync` to download the Google package.
+          # The default reporter (github-pr-annotations) works with the
+          # read-only GITHUB_TOKEN on forked PRs, unlike github-pr-check.
+          fail_on_error: false
+          filter_mode: added
+          files: docs
+
   test-package:
     name: Test PyPI package build
     runs-on: ubuntu-latest

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/.gitignore

@@ -68,3 +68,8 @@ target/
 venv
 
 .playwright-mcp
+
+# Vale external style packages synced by `vale sync` (see .vale.ini).
+# The Documenteer style (styles/Documenteer) and vocabulary (styles/config)
+# are committed; the downloaded Google package is not.
+/styles/Google/

documenteer-2.5.0b4/.python-version

@@ -0,0 +1 @@
+3.13

documenteer-2.5.0b4/.vale.ini

@@ -0,0 +1,137 @@
+# Vale configuration for Documenteer's documentation.
+#
+# Vale (https://vale.sh) provides advisory editorial linting of the prose in
+# docs/. Findings are informational: they never fail CI, and the nox session
+# is not part of the default sessions or the prek hooks. See docs/dev/vale.rst
+# for how to run and tune Vale.
+#
+# The Google package (styles/Google) is synced by `vale sync` and is
+# gitignored; the Documenteer style (styles/Documenteer) and vocabulary
+# (styles/config/vocabularies/Documenteer) are committed.
+
+StylesPath = styles
+
+# External style packages downloaded by `vale sync`.
+Packages = Google
+
+# Project vocabulary (styles/config/vocabularies/Documenteer/accept.txt).
+Vocab = Documenteer
+
+# Accept RST prose natively. Vale shells out to rst2html (docutils), which the
+# `vale` dependency group and the CI job install alongside Vale.
+[*.{rst,md}]
+BasedOnStyles = Vale, Google, Documenteer
+
+# --- Tuning (see docs/dev/vale.rst) -----------------------------------------
+# Google rules demoted or disabled because they produce a high volume of
+# low-value flags on this corpus. Each carries a one-line rationale.
+
+# Sentence-length heuristic fires constantly on legitimate technical prose.
+Google.Sentences = NO
+
+# Passive-voice detection is noisy and often wrong on procedural docs.
+Google.Passive = NO
+
+# Heading capitalization: this repo uses sentence case (checked by review),
+# but Google.Headings mis-parses RST directive titles and product names.
+Google.Headings = NO
+
+# "Will"/future tense is idiomatic in migration and release prose.
+Google.Will = suggestion
+
+# Ordinal/spelled-number and units rules flag many correct technical usages.
+Google.Units = suggestion
+Google.Ordinal = suggestion
+
+# House style permits contractions, and this rule agrees (it suggests
+# "don't" over "do not"), so keep it as a low-key suggestion.
+Google.Contractions = suggestion
+
+# Documenteer.We replaces Google.We (same "we" rule, with our wording/link).
+Google.We = NO
+
+# "RST", "TOML", "API", "DOI" etc. appear on nearly every page; spelling them
+# out on each mention is not this project's convention.
+Google.Acronyms = NO
+
+# Parenthetical asides are common and acceptable in this reference prose.
+Google.Parens = NO
+
+# Google.Latin flags "e.g."/"i.e.", which house style permits. Disable.
+Google.Latin = NO
+
+# Vale.Terms enforces case consistency across the whole corpus and fires (at
+# error level) on tokens that are correct in context: "sphinx" inside package
+# and module names versus "Sphinx" the project. Too noisy to be useful here.
+Vale.Terms = NO
+
+# Em-dash spacing preference; house style is relaxed about this.
+Google.EmDash = NO
+
+# Exclamation is covered adequately; keep as a suggestion.
+Google.Exclamation = suggestion
+
+# Google's word list prefers "preceding" over "above" and "app" over
+# "application", which misfire on "the example above" and on the Sphinx
+# application object (the two together were most of the warnings on this
+# corpus). Keep the list visible, but as suggestions.
+Google.WordList = suggestion
+Google.WordListCase = suggestion
+
+# "Lowercase the first word after a colon" fires mostly on proper nouns here
+# (Sphinx, Rubin, Documenteer, Zenodo).
+Google.Colons = suggestion
+
+# --- Path exclusions --------------------------------------------------------
+# These paths are excluded from linting. Vale merges glob sections, so an
+# excluded section must both clear BasedOnStyles *and* silence every rule that
+# was individually demoted above (Vale keeps a per-rule key set in a broader
+# section unless a narrower section overrides it).
+
+# Symlink to the scriv-generated CHANGELOG.md; edit changelog.d/ fragments.
+[docs/changelog.md]
+BasedOnStyles =
+Google.Will = NO
+Google.Units = NO
+Google.Ordinal = NO
+Google.Exclamation = NO
+Google.Contractions = NO
+Google.WordList = NO
+Google.WordListCase = NO
+Google.Colons = NO
+
+# Shared link targets only; no prose.
+[docs/_rst_epilog.rst]
+BasedOnStyles =
+Google.Will = NO
+Google.Units = NO
+Google.Ordinal = NO
+Google.Exclamation = NO
+Google.Contractions = NO
+Google.WordList = NO
+Google.WordListCase = NO
+Google.Colons = NO
+
+# Generated automodapi API stubs.
+[docs/dev/api/contents/**]
+BasedOnStyles =
+Google.Will = NO
+Google.Units = NO
+Google.Ordinal = NO
+Google.Exclamation = NO
+Google.Contractions = NO
+Google.WordList = NO
+Google.WordListCase = NO
+Google.Colons = NO
+
+# Technote templates, excluded from the Sphinx build as well.
+[docs/technotes/_templates/**]
+BasedOnStyles =
+Google.Will = NO
+Google.Units = NO
+Google.Ordinal = NO
+Google.Exclamation = NO
+Google.Contractions = NO
+Google.WordList = NO
+Google.WordListCase = NO
+Google.Colons = NO

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/CLAUDE.md

@@ -16,11 +16,11 @@ make init                    # Initialize development environment
 uv sync --extra technote --extra guide --group dev --group nox --group lint  # Install with all extras
 ```
 
-Tasks are run with [nox](https://nox.thea.codes/) (via [nox-uv](https://github.com/cthoyt/nox-uv)). Invoke nox through uv so the runner is provisioned automatically: `uv run --only-group=nox nox -s <session>`. The `test`, `typing`, and `demo` sessions are parametrized over both Python (3.12, 3.13) and Sphinx (8, 9, dev), so their session IDs carry both factors, e.g. `nox -s "test-3.13(sphinx='8')"`. uv furnishes the requested interpreter on demand. Bare `nox` runs a lean default set (3.13 × Sphinx 8/9); run `nox -l` to see the exact IDs.
+Tasks are run with [nox](https://nox.thea.codes/) (via [nox-uv](https://github.com/cthoyt/nox-uv)). Invoke nox through uv so the runner is provisioned automatically: `uv run --only-group=nox nox -s <session>`. The `test`, `typing`, and `demo` sessions are parametrized over both Python (3.12 through 3.15) and Sphinx (8, 9, dev), so their session IDs carry both factors, e.g. `nox -s "test-3.13(sphinx='8')"`. uv furnishes the requested interpreter on demand. The canonical development Python is declared in `.python-version` (currently 3.13); uv, nox's default sessions, and the GitHub Actions workflows all read it from there. Bare `nox` runs a lean default set (the canonical Python × Sphinx 8/9); run `nox -l` to see the exact IDs.
 
 ### Testing and Quality Assurance
 ```bash
-nox -s "test-3.13(sphinx='8')"   # Run tests on Python 3.13 with Sphinx 8.x (sphinx also '9'/'dev'; python also '3.12')
+nox -s "test-3.13(sphinx='8')"   # Run tests on Python 3.13 with Sphinx 8.x (sphinx also '9'/'dev'; python also '3.12', '3.14', '3.15')
 nox -s test                      # Run the full Python × Sphinx grid
 nox -s coverage-report           # Generate coverage report
 nox -s "typing-3.13(sphinx='8')" # Run mypy type checking
@@ -35,8 +35,11 @@ Coverage is opt-in via `DOCUMENTEER_COVERAGE=1`, which runs the test suite under
 ```bash
 nox -s docs                 # Build documentation
 nox -s docs-linkcheck       # Check documentation links
+nox -s vale                 # Advisory prose lint (Vale + Google style); `-- path.rst` for one file
 ```
 
+Vale is advisory only: it never fails CI, is not in the default nox sessions, and has no prek hook. Legitimate terms it flags go in `styles/config/vocabularies/Documenteer/accept.txt`; genuine typos get fixed in the source. See `docs/dev/vale.rst`.
+
 ### Cleanup
 ```bash
 make clean                  # Remove build artifacts
@@ -67,11 +70,11 @@ make clean                  # Remove build artifacts
 - `technote add-author`: Add authors to technote.toml from authordb
 - `technote sync-authors`: Sync author info from central database
 - `technote migrate`: Migrate legacy technotes to modern format
-- `technote lint`: Lint a technote's metadata, structure, and content (stable TN0xx/TN1xx/TN2xx rule codes, each with a landing page under docs/technotes/lint/)
+- `technote lint`: Lint a technote's metadata, structure, and content. Rule codes are stable and carry their rule set's prefix: `TN` rules (TN0xx/TN1xx/TN2xx) check what any technote needs, and `R` rules (R0xx/R1xx) check Rubin's conventions and services. Each code has a landing page under docs/technotes/lint/
 
 **Services** (`src/documenteer/services/`):
 - `technoteauthor.py`: Author management for technotes
-- `technotemigration.py`: Legacy technote migration logic
+- `technoteupdate.py`: Technote update and legacy-migration logic
 
 ### Key Design Patterns
 

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: documenteer
-Version: 2.5.0b2
+Version: 2.5.0b4
 Summary: Rubin Observatory / LSST Sphinx documentation tools, extensions, and configurations.
 License-Expression: MIT
 Project-URL: Homepage, https://documenteer.lsst.io
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Documentation
 Classifier: Topic :: Documentation :: Sphinx
 Classifier: Typing :: Typed
@@ -45,7 +46,7 @@ Requires-Dist: packaging
 Provides-Extra: guide
 Requires-Dist: autodoc_pydantic; extra == "guide"
 Requires-Dist: sphinx_design>=0.7.0; extra == "guide"
-Requires-Dist: pydata-sphinx-theme<0.21,>=0.19; extra == "guide"
+Requires-Dist: pydata-sphinx-theme<0.24,>=0.19; extra == "guide"
 Requires-Dist: sphinx-autodoc-typehints; extra == "guide"
 Requires-Dist: sphinx-automodapi; extra == "guide"
 Requires-Dist: sphinx-copybutton; extra == "guide"
@@ -62,7 +63,7 @@ Requires-Dist: sphinxcontrib-youtube; extra == "guide"
 Requires-Dist: sphinx-favicon; extra == "guide"
 Requires-Dist: sphinx-sitemap; extra == "guide"
 Provides-Extra: technote
-Requires-Dist: technote<0.10.0,>=0.9.1; extra == "technote"
+Requires-Dist: technote<0.13.0,>=0.12.0; extra == "technote"
 Requires-Dist: sphinx-prompt; extra == "technote"
 Requires-Dist: sphinxcontrib-mermaid>=1; extra == "technote"
 Requires-Dist: diagrams>=0.24; extra == "technote"

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/changelog.d/20260702_000000_DM-52076-technote-lint.md

@@ -1,9 +1,9 @@
 ### New features
 
-- Added a `documenteer technote lint` command that checks a technote's metadata, structure, and content before a build. Each finding carries a stable rule code so a bad technote is reported as a triageable finding rather than a traceback, and `--strict/-s` promotes warnings to errors so CI can fail on them. Every rule has a landing page under [documenteer.lsst.io/technotes/lint](https://documenteer.lsst.io/technotes/lint/index.html) describing the rule, showing a failing technote, and walking through the fix; the report links to the page for each rule it fires. The rules:
+- Added a `documenteer technote lint` command that checks a technote's metadata, structure, and content before a build. Each finding carries a stable rule code so a bad technote is reported as a triageable finding rather than a traceback, and `--strict/-s` promotes warnings to errors so CI can fail on them. Every rule has a landing page under [documenteer.lsst.io/technotes/lint](https://documenteer.lsst.io/technotes/lint/index.html) describing the rule, showing a failing technote, and walking through the fix; the report links to the page for each rule it fires. A code's prefix names the rule set it belongs to: `TN` rules check what any technote needs, and `R` rules check Rubin's conventions and services (its author database, its technote packaging). The rules:
 
-  - Structure: `technote.toml` exists (`TN004`), is valid TOML (`TN005`), and conforms to the technote schema (`TN001`); a Sphinx technote has an `index.{rst,md,ipynb}` content file (`TN006`); and `requirements.txt` declares `documenteer[technote]` (`TN002`) without pinning Sphinx separately (`TN003`).
-  - Authors: every author declares a resolvable `internal_id` in the Rubin author database — flagging authors missing an ID (`TN101`), IDs absent from or malformed in the database (`TN102`, an error), and an unreachable database (`TN103`, a transport-only warning). A missing or unknown ID is not a dead end: the finding names the ID the author probably wants — `Did you mean 'alsayyady' (matched by ORCID)?` — by searching the author database for their name and accepting only a confident match (a matching ORCID, or a single near-exact name match); an ambiguous search or failed lookup silently leaves the plain message.
+  - Structure: `technote.toml` exists (`TN004`), is valid TOML (`TN005`), and conforms to the technote schema (`TN001`); a Sphinx technote has an `index.{rst,md,ipynb}` content file (`TN006`); and `requirements.txt` declares `documenteer[technote]` (`R002`) without pinning Sphinx separately (`R003`).
+  - Authors: every author declares a resolvable `internal_id` in the Rubin author database — flagging authors missing an ID (`R101`), IDs absent from or malformed in the database (`R102`, an error), and an unreachable database (`R103`, a transport-only warning). A missing or unknown ID is not a dead end: the finding names the ID the author probably wants — `Did you mean 'alsayyady' (matched by ORCID)?` — by searching the author database for their name and accepting only a confident match (a matching ORCID, or a single near-exact name match); an ambiguous search or failed lookup silently leaves the plain message.
   - Content: the technote declares its abstract with the abstract directive (`TN201`) rather than an ordinary section heading (`TN202`), the content file can be parsed (`TN203`, for example a corrupt notebook), and the abstract directive has a body (`TN204`). `TN204` and `TN202` findings locate the problem as `file:line`; the common `TN204` cause is abstract text left unindented under `.. abstract::`, which reStructuredText reads as an empty directive, publishing an empty abstract and `og:description` while the source looks fine. The abstract scan matches directive names in any letter case (docutils lowercases them), accepts an abstract written on the `.. abstract::` marker line itself, and resolves `.. include::` and `` ```{include} `` directives one level deep so an abstract factored into another file is still found.
 
   An unparseable `technote.toml` no longer hides the rest of the report: only the author checks, which need the parsed metadata, are skipped. When a `TN001` schema failure comes from a historical author-name form — `name = { name = "Full Name" }` (removed in technote 0.5) or `name = { given_names = "...", family_names = "..." }` (renamed in 2023) — the finding names the legacy form, shows the modern `name = { given = "...", family = "..." }` replacement, and points at `documenteer technote migrate`. Technote-series repositories that are not Sphinx projects — no index content file and no `conf.py`, built through the shared technote CI with a custom build command — are linted for their `technote.toml` alone, so a healthy non-Sphinx technote passes.

{documenteer-2.5.0b2 → documenteer-2.5.0b4}/changelog.d/20260706_000000_jonathan_DM_55386_linkcheck_service.md

@@ -1,4 +1,4 @@
 ### New features
 
-- The user-guide configuration now checks external links with Ook's link-check service. The new `documenteer.ext.linkcheckservice` extension registers a builder over Sphinx's `linkcheck` name, so existing `make linkcheck` invocations transparently submit the project's external links to the service and report its cached, retry-buffered results, writing a machine-readable `linkcheck.json` artifact to the build output. Submissions authenticate with a bearer token from `OOK_TOKEN`; `broken` links fail the build, while `redirected`, `failing`, `unsupported`, and `blocked` links are reported at info level so a `-W` build doesn't fail on them (matching Sphinx's built-in linkcheck). New `[sphinx.linkcheck]` settings in `documenteer.toml` configure the integration (`use_service`, `service_url`, `poll_budget`, `strict`, `origin_base_url`). When `OOK_TOKEN` is missing or rejected the builder falls back to Sphinx's built-in in-process `linkcheck`; when the service is unreachable or the poll budget is exhausted it warns and exits 0 by default, or fails the build if `strict = true`. Set `use_service = false` to always use the built-in builder.
+- The user-guide configuration now checks external links with Ook's link-check service. The new `documenteer.ext.linkcheckservice` extension registers a builder over Sphinx's `linkcheck` name, so existing `make linkcheck` invocations transparently submit the project's external links to the service and report its cached, retry-buffered results, writing a machine-readable `linkcheck.json` artifact to the build output. Submissions authenticate with a bearer token from `OOK_TOKEN`; `broken` links fail the build, while `redirected`, `failing`, `unsupported`, and `blocked` links are reported at info level so a `-W` build doesn't fail on them (matching Sphinx's built-in linkcheck). New `[sphinx.linkcheck]` settings in `documenteer.toml` configure the integration (`use_service`, `service_url`, `poll_budget`, `strict`, `origin_base_url`). When `OOK_TOKEN` is missing or rejected the builder falls back to Sphinx's built-in in-process `linkcheck`; when the service is unreachable or the poll budget is exhausted it falls back the same way by default, or fails the build if `strict = true`. Set `use_service = false` to always use the built-in builder.
 - The technote configuration also checks external links with the service, deriving the origin base URL from the technote's canonical URL in `technote.toml` (falling back to `https://<handle>.lsst.io`). Every setting is overridable in the technote's `conf.py` after the preset import (for example `documenteer_linkcheck_use_service = False`), and the technote `tox.ini` template now passes `OOK_TOKEN` through, so a technote whose CI sets the token opts in and one without a token falls back to the built-in `linkcheck`.