Repository navigation
chore: upgrade docs tooling to latest stable; hide badges from the man page - #498
Merged
Merged
Conversation
…nventories' Drop the upper bounds on the documentation groups, let ruff format Markdown again, and upgrade the lock to the latest stable releases. mkdocstrings-python >=1.14 supports the 'inventories' key that replaces the removed 'import'.
…ling The newer docutils renders each README badge as '[image: ...] <url>' in the man page, so the export script now shows the badge row in html output only. Regenerate docs/index.rst (newer pandoc whitespace) and let ruff format the Python example in docs/install_and_use.md (and its rST copy).
nandgator
force-pushed
the
docs-tooling-upgrade
branch
from
October 10, 2026 08:22
0332c02 to
5985f51
Compare
nandgator
added a commit
that referenced
this pull request
Oct 10, 2026
nandgator
added a commit
that referenced
this pull request
Oct 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rebased onto master after #495 merged.
Summary
#495 deliberately keeps the documentation tooling at the versions that produced the old output. This PR lifts that restriction and moves everything to the latest stable releases, then deals with what changes.
docs-offlineanddocs-onlinegroups, and let ruff format Markdown again (ruff 0.17 formats Python blocks in.mdfiles).uv lock --upgrade: sphinx 9, furo 2025.12.19, myst-parser 5.1, docutils 0.22.4, pypandoc-binary 1.17, mkdocstrings 1.0.6 and mkdocstrings-python 2.0.9.import:key toinventories:.importwas deprecated in mkdocstrings-python 1.14 and removed in 2.0 (this was breakingmkdocs build). I checked every version from 1.10.5: the key is supported from 1.14.0, so the floor ismkdocstrings-python>=1.14.0. Builds with both 1.19.0 and 2.0.9.package/export: show the README badge row in html output only (see below).docs/index.rst,docs/install_and_use.{md,rst}).Is the changed output a problem?
Regenerated with the real
./package/roll.shand compared with the old output:[image: PyCQA] [image] <url> ..... only:: html, so the web docs keep their badges and the man page drops the row.Documentation <https://...>).EX/.EEinstead of.nf/.ft C; the old groff "cannot select font 'C'" warnings are gone.SH Author/.SH Copyrightinstead of upper caseNote:instead ofNOTE:, footer comments, spacingWeb docs: compared the visible article text of every page (the same 20 API pages plus index, install and use): identical. Only theme assets, version strings and boilerplate differ.
docs/index.rstchanges only in bullet whitespace (newer pandoc).docs/install_and_use.mdgets a blank line and double quotes in its Python example from ruff.Checked on this branch:
package/export man,webanddoc(mkdocs) all build with rc=0 and no new warnings (theimportFutureWarning is gone); 1069 tests,ruff check,ruff format --checkandpyrightpass.🤖 Generated with Claude Code