Conversation
why: Adopt the v0.0.1a8 release of the shared docs platform — argparse domain, CSS namespace unification under gp-sphinx-*, sphinx>=8.1 floor, typed env.domains.* accessors, autodoc layout and badges package renames, py.typed marker for typehints-gp. what: - Bump gp-sphinx and sphinx-autodoc-api-style pins from 0.0.1a7 to 0.0.1a8 across every dependency group - Replace sphinx-argparse-neo==0.0.1a7 with sphinx-autodoc-argparse==0.0.1a8, and update the extension name in docs/conf.py from sphinx_argparse_neo.exemplar to sphinx_autodoc_argparse.exemplar - Refresh uv.lock against the published workspace See also: https://pypi.org/project/gp-sphinx/0.0.1a8/
why: The two grid-item-card blocks in the CLI Reference page used
URL-fragment 🔗 options (`#command`, `#supported-vcs`) with
:link-type: url. MyST-parser treats `#` inside a directive's
options block as a YAML-style comment, so the fragment was
stripped and 🔗 was left with an empty value. That produced
five cascading `sphinx-build -W` warnings: two
[myst.directive_comments], two [myst.directive_option] ("Invalid
option value for 'link': None"), and one [design.grid] ("All
children of a 'grid-row' should be 'grid-item'") because the
half-parsed card nodes weren't valid grid-items for sphinx-design
0.7's stricter row-children check.
what:
- Switch both grid-item-cards to :link-type: ref with bare label
targets (🔗 cli-main, 🔗 cli-supported-vcs). No `#`
in the options block -> no MyST comment interpretation -> the
cards parse cleanly as grid-items and the cascading
design.grid warning goes away.
- Add a (cli-supported-vcs)= label before the `## Supported VCS`
heading so the new ref target resolves. cli-main already
existed above `## Command`.
- Does not address the remaining "Duplicate ID: usage" critical
from the manual `## Usage` heading colliding with the
.. argparse:: directive's built-in Usage section — that lands
in a separate commit for reviewability.
…llision why: The CLI Reference page has both a manual `## Usage` MyST heading (showing `g <cmd>` -> underlying VCS invocation equivalences) and a `.. argparse::` directive block that emits its own auto-generated "Usage" section (showing the synopsis line). Both produced the docutils anchor id `usage` on the same page, tripping a `CRITICAL: Duplicate ID: "usage" [docutils]` warning and failing `sphinx-build -W`. what: - Rename the manual section from `## Usage` to `## Usage examples`. The new slug `usage-examples` no longer collides with argparse's `usage`, and the heading describes the actual content better (it's a collection of equivalence examples, not a synopsis). - No content changes; only the heading text. - With this + the prior ref-link commit, `uv run sphinx-build -W -b dirhtml docs docs/_build/html` now passes cleanly (was: 6 warnings treated as errors).
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #54 +/- ##
=======================================
Coverage 96.89% 96.89%
=======================================
Files 5 5
Lines 129 129
=======================================
Hits 125 125
Misses 4 4 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
tony
force-pushed
the
autodoc-improvements
branch
from
dc36d0b to
eafcc21
Compare
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
2 participants
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.
Summary
0.0.1a7→0.0.1a8uv.lockagainst the published workspacesphinx-argparse-neo==0.0.1a7→sphinx-autodoc-argparse==0.0.1a8and updates the extension path indocs/conf.pyautodoc-improvementsbranchCHANGESbullet noting the bumpWhat's new in gp-sphinx 0.0.1a8
:argparse:*roles, indices, xref resolution)gp-sphinx-*BEMsphinx>=8.1floor with typedenv.domains.*accessorssphinx-autodoc-layout→sphinx-ux-autodoc-layout,sphinx-autodoc-badges→sphinx-ux-badgespy.typedmarker added tosphinx-autodoc-typehints-gp# bump-version: skip-filesentinel in the bump scriptTest plan
uv sync --all-extras --group dev— cleanuv run ruff check . --fix --show-fixes— all passeduv run ruff format .— no changesuv run mypy— no issuesuv run pytest -q— 9 passedjust build-docs— build succeeded, 6 warnings