From 1af5cd76db5acb21b2b0c50486761544e9cdc672 Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Fri, 24 Jul 2026 14:55:37 -0400 Subject: [PATCH] docs: switch from mkdocs to properdocs (#2946) properdocs is a drop-in MkDocs fork by the original MkDocs maintainers. The existing plugins (include-markdown, macros, intersphinx) and pymdown extensions work unchanged; themes are unbundled, so the readthedocs theme comes from properdocs-theme-readthedocs. Assisted-by: ClaudeCode:claude-fable-5 --- .github/workflows/test.yml | 2 +- .readthedocs.yml | 2 +- AGENTS.md | 4 ++-- azure-pipelines.yml | 2 +- noxfile.py | 4 +++- mkdocs.yml => properdocs.yml | 0 pyproject.toml | 3 ++- 7 files changed, 10 insertions(+), 7 deletions(-) rename mkdocs.yml => properdocs.yml (100%) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index e81197e1..bb741fce 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -23,7 +23,7 @@ on: - .travis.yml - README.md - azure-pipelines.yml - - mkdocs.yml + - properdocs.yml - noxfile.py workflow_dispatch: # allow manual runs on branches without a PR diff --git a/.readthedocs.yml b/.readthedocs.yml index 70d3153a..606ba546 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -8,4 +8,4 @@ build: - asdf plugin add uv - asdf install uv latest - asdf global uv latest - - NO_COLOR=1 uv run --python 3.14 --managed-python --no-dev --group docs mkdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html + - NO_COLOR=1 uv run --python 3.14 --managed-python --no-dev --group docs properdocs build --strict --site-dir $READTHEDOCS_OUTPUT/html diff --git a/AGENTS.md b/AGENTS.md index 186cc65e..627dbc16 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -11,7 +11,7 @@ - `nox -s tests -- test -k before_build` — single integration test/file via pytest `-k`. - `nox -s lint` — run all linters (pre-commit/prek). - `nox -s pylint` — run pylint separately (not in pre-commit). -- `nox -s docs` — mkdocs serve (interactive) or build (non-interactive). +- `nox -s docs` — properdocs serve (interactive) or build (non-interactive). - Set up local dev env at `.venv`: `uv sync` (dependency groups used). ## Project layout @@ -19,7 +19,7 @@ - `test/` — **integration tests** (expensive, run actual wheel builds). - `unit_test/` — **unit tests** (fast, no wheel builds). - `bin/` — maintainer scripts (update pins, generate README tables, schema, etc.). -- `docs/` — mkdocs source. +- `docs/` — properdocs (MkDocs fork) source. ## Testing specifics - Three test suites exist, run in this order by `bin/run_tests.py`: diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 0f2621d8..657428ff 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -12,7 +12,7 @@ pr: - .readthedocs.yml - .travis.yml - README.md - - mkdocs.yml + - properdocs.yml - noxfile.py jobs: diff --git a/noxfile.py b/noxfile.py index 98fd35ac..a4d46e7c 100755 --- a/noxfile.py +++ b/noxfile.py @@ -228,7 +228,9 @@ def docs(session: nox.Session) -> None: """ pyproject = nox.project.load_toml() session.install("-e.", *nox.project.dependency_groups(pyproject, "docs")) - session.run("mkdocs", "serve" if session.interactive else "build", "--strict", *session.posargs) + session.run( + "properdocs", "serve" if session.interactive else "build", "--strict", *session.posargs + ) @nox.session(default=False) diff --git a/mkdocs.yml b/properdocs.yml similarity index 100% rename from mkdocs.yml rename to properdocs.yml diff --git a/pyproject.toml b/pyproject.toml index b0c881c3..30c4e48b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -68,7 +68,8 @@ docs = [ "mkdocs-include-markdown-plugin==7.1.8", "mkdocs-intersphinx>=0.1.1; python_version >= '3.12'", "mkdocs-macros-plugin>=1.4.1", - "mkdocs==1.6.1", + "properdocs==1.6.7", + "properdocs-theme-readthedocs", "pymdown-extensions", "rich", ]