docs: switch from mkdocs to properdocs

[henryiii]

I evaluated zensical and Great Docs too; zensical is still missing stuff we need and forces the material theme, and Great Docs uses a quarto binary (heavy) and is really focused on API rather than narrative.

MkDocs is no longer developed publicly (or at all?) (along with httpx, same author), and hasn't had a new release in two years. If there is another release, it won't support plugins. See the slow collapse of mkdocs for context.

🤖 AI text below 🤖

Switches the docs build from MkDocs to properdocs, the drop-in MkDocs fork maintained by the original MkDocs authors.

Changes:

• mkdocs.yml → properdocs.yml (content unchanged; properdocs errors on an implicit mkdocs.yml fallback)
• pyproject.toml: mkdocs==1.6.1 → properdocs==1.6.7, plus properdocs-theme-readthedocs (themes are unbundled from the core package)
• Command name updated in noxfile.py and .readthedocs.yml; CI path filters updated

The existing plugins (mkdocs-include-markdown-plugin, mkdocs-macros-plugin, mkdocs-intersphinx) and pymdown extensions work unchanged — properdocs reads the mkdocs.plugins/mkdocs.themes entry points. properdocs build --strict passes locally, including the macros-generated options page and the intersphinx inventory.

Draft: evaluating whether we want to make this switch; also worth checking the Read the Docs build preview before merging.

[joerick]

Nice! This seems like a step forward, and away from the unmaintained mkdocs.

(I would like to modernise the docs at some point, and make it easier to include the more custom elements (e.g. the envvar/toml tabs, the options page headers, the 'how it works' diagram) in a less hacky way. I do have half an eye on Starlight with this in mind. But that's a topic for another day.)

[joerick]

I know it's draft but I've had a good browse through the RtD build and it looks identical to me!

[henryiii]

The only thing I saw when looking through was the missing identifier (which has nothing to do with this change), so I can take it out of draft. GH is having some issues at the moment, I think.