fix: scope toml→ini to docs, pin schema-store, add docs CI

- Revert the toml→ini fence change in src/sp_repo_review/checks/*.py;
  those docstrings render in repo-review itself, so the docs-only
  highlighter workaround (code_fence cog helper) should not leak into
  the published package.
- Restore validate-pyproject-schema-store pin to 2026.04.03 in the
  repo_review anywidget deps (was unintentionally downgraded).
- Add a PR-time MyST build check (reusable-docs.yml) wired into CI via
  change detection on docs/helpers/package.json/bun.lock/.readthedocs.yaml.
- Clarify in AGENTS.md that the ini-for-toml workaround is docs-only.

Assisted-by: ClaudeCode:claude-opus-4.8

Author: henryiii

.github/workflows/ci.yml

@@ -25,12 +25,18 @@ jobs:
     if: fromJSON(needs.change-detection.outputs.run-rr)
     uses: ./.github/workflows/reusable-rr-tests.yml
 
+  docs:
+    needs: change-detection
+    if: fromJSON(needs.change-detection.outputs.run-docs)
+    uses: ./.github/workflows/reusable-docs.yml
+
   pass:
     if: always()
     needs:
       - change-detection
       - cookie
       - rr-tests
+      - docs
     runs-on: ubuntu-latest
 
     steps:
@@ -50,5 +56,11 @@ jobs:
               || '
               rr-tests,
               '
+            }} ${{
+              fromJSON(needs.change-detection.outputs.run-docs)
+              && ''
+              || '
+              docs,
+              '
             }}
           jobs: ${{ toJSON(needs) }}

.github/workflows/reusable-change-detection.yml

@@ -8,6 +8,9 @@ on:
       run-rr:
         description: Whether or not run the repo-review tests
         value: ${{ jobs.change-detection.outputs.run-rr || false }}
+      run-docs:
+        description: Whether or not to build the docs site
+        value: ${{ jobs.change-detection.outputs.run-docs || false }}
 
 jobs:
   change-detection:
@@ -17,6 +20,7 @@ jobs:
     outputs:
       run-cookie: ${{ steps.cookie-changes.outputs.run-cookie || false }}
       run-rr: ${{ steps.rr-changes.outputs.run-rr || false }}
+      run-docs: ${{ steps.docs-changes.outputs.run-docs || false }}
     steps:
       - uses: actions/checkout@v6
 
@@ -63,3 +67,24 @@ jobs:
           steps.changed-rr-files.outputs.added_modified_renamed != '[]'
         id: rr-changes
         run: echo "run-rr=true" >> "${GITHUB_OUTPUT}"
+
+      - name: Changed docs-related files
+        if: github.event_name == 'pull_request'
+        id: changed-docs-files
+        uses: Ana06/get-changed-files@v2.3.0
+        with:
+          format: "json"
+          filter: |
+            .github/workflows/ci.yml
+            .github/workflows/reusable-docs.yml
+            docs/**
+            helpers/**
+            package.json
+            bun.lock
+            .readthedocs.yaml
+      - name: Set a flag for building the docs
+        if: >-
+          github.event_name != 'pull_request' ||
+          steps.changed-docs-files.outputs.added_modified_renamed != '[]'
+        id: docs-changes
+        run: echo "run-docs=true" >> "${GITHUB_OUTPUT}"

.github/workflows/reusable-docs.yml

@@ -0,0 +1,26 @@
+name: Docs
+
+on:
+  workflow_call:
+
+jobs:
+  build:
+    name: Build MyST site
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build the docs
+        run: bun run build
+
+      - name: Upload built site
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html

AGENTS.md

@@ -85,4 +85,8 @@ The noxfile generates temporary projects for **all 9 backends** × **vcs on/off*
 - Tab-sets use `:sync: <tab-name>` for cross-page tab synchronization, where the
   sync key is the tab label itself (e.g., `sphinx`, `mkdocs`,
   `trusted-publishing`, `scikit-build-core`).
-- TOML code blocks use "ini" to get syntax highlighting for now.
+- TOML code blocks in the docs use "ini" to get syntax highlighting for now.
+  This is applied only at the docs layer (the `code_fence` cog helper in
+  `helpers/cog_helpers.py` rewrites `toml`→`ini`); do **not** change the `toml`
+  fences in the `src/sp_repo_review/checks/*.py` docstrings, which are rendered
+  by repo-review itself, not this site.

docs/pages/guides/repo_review.md

@@ -29,7 +29,7 @@ pipx run 'sp-repo-review[cli]' <path to repo>
     "repo-review~=1.1.0",
     "sp-repo-review==2026.04.04",
     "validate-pyproject[all]~=0.25.0",
-    "validate-pyproject-schema-store==2026.03.29",
+    "validate-pyproject-schema-store==2026.04.03",
   ]
 }
 :::

src/sp_repo_review/checks/mypy.py

@@ -45,7 +45,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         your settings already, ignore this check or set `strict = false`
         explicitly.
 
-        ```ini
+        ```toml
         [tool.mypy]
         strict = true
         ```
@@ -91,7 +91,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         static checks), so it's okay to set it to false if you need to. But try
         it first - it can catch real bugs too.
 
-        ```ini
+        ```toml
         [tool.mypy]
         warn_unreachable = true
         ```
@@ -117,7 +117,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         will force all skips in your project to include the error code, which
         makes them more readable, and avoids skipping something unintended.
 
-        ```ini
+        ```toml
         [tool.mypy]
         enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
         ```
@@ -142,7 +142,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         Must have `"redundant-expr"` in `enable_error_code = [...]`. This helps
         catch useless lines of code, like checking the same condition twice.
 
-        ```ini
+        ```toml
         [tool.mypy]
         enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
         ```
@@ -167,7 +167,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         Must have `"truthy-bool"` in `enable_error_code = []`. This catches
         mistakes in using a value as truthy if it cannot be falsy.
 
-        ```ini
+        ```toml
         [tool.mypy]
         enable_error_code = ["ignore-without-code", "redundant-expr", "truthy-bool"]
         ```

src/sp_repo_review/checks/noxfile.py

@@ -179,7 +179,7 @@ def check(noxfile: Noxfile | None) -> bool | None:
         """
         You should have a script block with nox in it, for example:
 
-        ```ini
+        ```toml
         # /// script
         # dependencies = ["nox"]
         # ///

src/sp_repo_review/checks/pyproject.py

@@ -170,7 +170,7 @@ def check(pyproject: dict[str, Any]) -> bool:
         These are better than the old `extras` system for tests, docs, and other
         dependencies that are not needed for PyPI installs.
 
-        ```ini
+        ```toml
         [dependency-groups]
         dev = [ {{ include-group = "test" }} ]
         test = [ "pytest" ]
@@ -215,7 +215,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         support `pyproject.toml` ini configuration) or 9 (first version to
         support native configuration and toml config files).
 
-        ```ini
+        ```toml
         # Old pytest
         [tool.pytest.ini_options]
         minversion = "6"
@@ -244,7 +244,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         """
         The `testpaths` setting should be set to a reasonable default.
 
-        ```ini
+        ```toml
         # Old pytest
         [tool.pytest.ini_options]
         testpaths = ["tests"]
@@ -270,7 +270,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         `log_level` should be set. This will allow logs to be displayed on
         failures.
 
-        ```ini
+        ```toml
         # Old pytest
         [tool.pytest.ini_options]
         log_level = "INFO"
@@ -297,7 +297,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         be set. You can manually specify if a check should be strict when
         setting each xfail.
 
-        ```ini
+        ```toml
         [tool.pytest.ini_options]
         xfail_strict = true
 
@@ -326,7 +326,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         `strict_config` or `strict` should be set. This forces an error if a
         config setting is misspelled.
 
-        ```ini
+        ```toml
         # Old pytest
         [tool.pytest.ini_options]
         addopts = ["-ra", "--strict-config", "--strict-markers"]
@@ -357,7 +357,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         `strict_markers` or `strict` should be set. This forces test markers to
         be specified in config, avoiding misspellings.
 
-        ```ini
+        ```toml
         # Old pytest
         [tool.pytest.ini_options]
         addopts = ["-ra", "--strict-config", "--strict-markers"]
@@ -387,7 +387,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         An explicit summary flag like `-ra` should be in `addopts = [...]`
         (print summary of all fails/errors).
 
-        ```ini
+        ```toml
         # Old pytest
         [tool.pytest.ini_options]
         addopts = ["-ra", "--strict-config", "--strict-markers"]
@@ -416,7 +416,7 @@ def check(pytest: tuple[PytestFile, dict[str, Any]]) -> bool:
         `filterwarnings` must be set (probably to at least `["error"]`). Python
         will hide important warnings otherwise, like deprecations.
 
-        ```ini
+        ```toml
         # Old pytest
         [tool.pytest.ini_options]
         filterwarnings = ["error"]

src/sp_repo_review/checks/ruff.py

@@ -139,7 +139,7 @@ def check(cls: type[RF1xxMixin], ruff: dict[str, Any]) -> bool:
         """
         Must select the {self.name} `{self.code}` checks. Recommended:
 
-        ```ini
+        ```toml
         [tool.ruff.lint]
         extend-select = [
           "{self.code}",  # {self.name}