feat: move to mystmd

.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

.gitignore

@@ -148,7 +148,6 @@ docs/assets/js/repo-review-app.min.js.map
 # NodeJS stuff, just in case (developer tooling)
 node_modules/
 package-lock.json
-package.json
 
 # readthedocs
 _readthedocs

.pre-commit-config.yaml

@@ -32,7 +32,7 @@ repos:
     rev: "v0.15.14"
     hooks:
       - id: ruff-check
-        args: ["--fix", "--show-fixes"]
+        args: ["--fix"]
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/pygrep-hooks
@@ -63,8 +63,13 @@ repos:
     rev: "v3.8.3"
     hooks:
       - id: prettier
-        types_or: [yaml, markdown, html, css, scss, javascript, json]
-        args: [--prose-wrap=always]
+        types_or: [yaml, html, css, scss, javascript, json]
+
+  - repo: https://github.com/rvben/rumdl-pre-commit
+    rev: v0.2.0
+    hooks:
+      - id: rumdl
+        args: [--no-exclude] # Disable all exclude patterns
 
   - repo: https://github.com/crate-ci/typos
     rev: "v1.46.3"
@@ -92,5 +97,5 @@ repos:
         name: Cog the pages
         language: python
         entry: cog -P -r -I ./helpers
-        files: "^docs/pages/guides/(packaging_compiled|docs|tasks|gha_basic).md|^copier.yml|^docs/_includes/pyproject.md"
+        files: "^docs/pages/guides/(packaging_compiled|docs|tasks|gha_basic).md|^copier.yml|^docs/_partials/pyproject.md"
         additional_dependencies: [cogapp, cookiecutter, tomlkit]

.readthedocs.yaml

@@ -1,21 +1,20 @@
-# .readthedocs.yaml
-# Read the Docs configuration file
+# Read the Docs configuration file for myst
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
 # Required
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
   os: ubuntu-24.04
-
   tools:
-    ruby: "3.4"
-
+    nodejs: "24"
   commands:
-    - ./helpers/fetch_repo_review_app.sh
-    - bundle install
-    - >
-      JEKYLL_ENV=production bundle exec jekyll build --destination
-      _readthedocs/html --baseurl $(echo -n "$READTHEDOCS_CANONICAL_URL" | cut
-      -d '/' -f 4-)
+    # Install myst
+    - npm install -g mystmd
+    # Build the site
+    - cd docs && myst build --html
+    # Copy the output to Read the Docs expected location
+    - mkdir -p $READTHEDOCS_OUTPUT/html/
+    - cp -r docs/_build/html/. "$READTHEDOCS_OUTPUT/html"
+    # Clean up build artifacts
+    - rm -rf docs/_build

AGENTS.md

@@ -0,0 +1,92 @@
+# Agent Guide for scientific-python/cookie
+
+This repo has three distinct concerns: a **cookiecutter/copier template** for
+new Python projects (`{{cookiecutter.project_name}}/`), a **repo-review plugin**
+(`src/sp_repo_review/`), and a **MyST/MystMD-based developer guide** (`docs/`).
+
+## Key commands
+
+### sp-repo-review (the package)
+
+- Run tests: `uv run pytest` (or `uvx nox -s rr_tests`)
+- Run linting (pre-commit via prek): `uvx nox -s rr_lint`
+- Run pylint: `uvx nox -s rr_pylint`
+- Run the CLI: `uvx nox -s rr_run -- <path>`
+- Regenerate README check list via cog: `uvx nox -s readme`
+- Build wheel/sdist: `uvx nox -s rr_build`
+
+Important: tests run with `PYTHONWARNDEFAULTENCODING=1`.
+
+### Cookie template validation
+
+The noxfile generates temporary projects for **all 9 backends** × **vcs on/off**
+× **3 docs engines** (sphinx/mkdocs/zensical). These are slow.
+
+- `nox -s "tests(hatch)"` — run generated project tests for a single backend
+- `nox -s "lint(hatch)"` — run pre-commit (`prek`) on generated project
+- `nox -s "dist(hatch)"` — verify build output includes LICENSE
+- `nox -s "native(hatch)"` — test hatch/pdm/poetry native test runners
+- `nox -s compare_copier` — verify cookiecutter and copier produce identical
+  files
+- `nox -s compare_cruft` — verify cookiecutter and cruft produce identical files
+- `nox -s gha_bump` — bump GitHub Actions versions across docs and templates
+- `nox -s pc_bump` — bump pre-commit hook versions across docs and templates
+
+## Architecture notes
+
+- **Template directory**: `{{cookiecutter.project_name}}/` contains the
+  cookiecuttter template. Copier reads `copier.yml`; cookiecutter reads
+  `cookiecutter.json`. Keep them in sync; `compare_copier` checks this.
+- **Entry points**: `sp_repo_review` registers `repo-review`
+  checks/families/fixtures via `[project.entry-points]` in `pyproject.toml`.
+- **Generated docs**: The README check list (line ~300+) is a cog block. Do not
+  edit it by hand; run `nox -s readme` or cog will fail in CI.
+- **Cookie template `.pre-commit-config.yaml`** uses `prek` (a Rust-based
+  pre-commit alternative), not `pre-commit`.
+- **Ruff hook ID**: `.pre-commit-config.yaml` uses `ruff-check` as the hook id
+  (not `ruff`), for pre-commit 4.x compatibility.
+
+## Style and conventions
+
+- `tool.pytest.ini_options.norecursedirs` excludes
+  `{{cookiecutter.project_name}}` so pytest does not descend into the template
+  directory.
+- `tool.ruff.extend-exclude` also excludes `\{\{cookiecutter.project_name\}\}`
+  (double-escaped in TOML).
+- `tool.mypy.python_version = "3.10"`; the `sp_repo_review.*` override enforces
+  `disallow_untyped_defs=True`.
+- `tool.pylint.master.ignore-paths` ignores `src/sp_repo_review/_version.py`
+  (auto-generated by hatch-vcs).
+- Ruff selects `ALL` with many ignores; notable: `S101` (assert) and `D`
+  (docstrings) are globally disabled.
+
+## CI quirks
+
+- CI uses change detection to decide whether to run cookie tests or rr-tests.
+  Both are required to pass for the `pass` job.
+- rr-tests matrix runs on Python 3.10, 3.12, 3.14 across ubuntu/macos/windows.
+- Cookie tests reuse the same `reusable-cookie.yml` workflow.
+
+## Docs site (MyST)
+
+- Migrated from Jekyll to [MyST](https://mystmd.org) (JupyterBook 2.0) using the
+  `scientific-python-myst-theme`.
+- Node/Bun-based; from the repo root, run `bun install` then `bun run build` to
+  build the site.
+- Config: `docs/myst.yml` (TOC, project settings),
+  `docs/config/scientific-python.yml` (theme options).
+- Custom plugin: `docs/rr-role.mjs` — provides `{rr}` inline role for
+  repo-review badge spans.
+- Custom CSS: `docs/assets/css/site.css` — only `.rr-btn` badge styling remains.
+- Docs pages in `docs/pages/` contain cog blocks that auto-generate config
+  examples from the template.
+- The repo-review interactive page is embedded using an `{anywidget}` directive
+  (see `docs/pages/guides/repo_review.md`).
+- 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 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.