Skip to content

chore: upgrade docs tooling to latest stable; hide badges from the man page - #498

Merged
nandgator merged 2 commits into
masterfrom
docs-tooling-upgrade
Oct 10, 2026
Merged

nandgator merged 2 commits into
masterfrom
docs-tooling-upgrade

Conversation

@nandgator

@nandgator nandgator commented Oct 10, 2026 •

Copy link
Copy Markdown
Collaborator

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.

  • Drop the upper bounds on the docs-offline and docs-online groups, and let ruff format Markdown again (ruff 0.17 formats Python blocks in .md files).
  • 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.
  • mkdocs: rename the mkdocstrings import: key to inventories:. import was deprecated in mkdocstrings-python 1.14 and removed in 2.0 (this was breaking mkdocs build). I checked every version from 1.10.5: the key is supported from 1.14.0, so the floor is mkdocstrings-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).
  • Regenerate the tracked docs (docs/index.rst, docs/install_and_use.{md,rst}).

Is the changed output a problem?

Regenerated with the real ./package/roll.sh and compared with the old output:

Change in the man page Verdict
The five badge images rendered as [image: PyCQA] [image] <url> ... Real regression (about 8 lines of noise at the top). Fixed here: the badge row is wrapped in .. only:: html, so the web docs keep their badges and the man page drops the row.
Hyperlinks now show their URL (Documentation <https://...>) Improvement: the Resources links previously had no visible URL at all.
Code blocks use .EX/.EE instead of .nf/.ft C; the old groff "cannot select font 'C'" warnings are gone Fine: needs groff 1.22.4 or newer, which any current Debian or Ubuntu has.
.SH Author / .SH Copyright instead of upper case Cosmetic: docutils 0.22 emits these literally. Not patched around.
Note: instead of NOTE:, footer comments, spacing Cosmetic.

Web 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.rst changes only in bullet whitespace (newer pandoc). docs/install_and_use.md gets a blank line and double quotes in its Python example from ruff.

Checked on this branch: package/export man, web and doc (mkdocs) all build with rc=0 and no new warnings (the import FutureWarning is gone); 1069 tests, ruff check, ruff format --check and pyright pass.

🤖 Generated with Claude Code

…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
nandgator force-pushed the docs-tooling-upgrade branch from 0332c02 to 5985f51 Compare October 10, 2026 08:22
@nandgator
nandgator changed the base branch from adopt-uv-dependency-groups to master October 10, 2026 08:22
@nandgator nandgator closed this Oct 10, 2026
@nandgator nandgator reopened this Oct 10, 2026
@nandgator
nandgator merged commit cdbe4af into master Oct 10, 2026
7 checks passed
nandgator added a commit that referenced this pull request Oct 10, 2026
nandgator added a commit that referenced this pull request Oct 10, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant