docs: Replace sphinx-argparse with sphinx_argparse_neo #1009
Conversation
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
why: Custom extensions provide better control over CLI documentation rendering and eliminate external dependency on sphinx-argparse. what: - Add docs/_ext/sphinx_argparse_neo/ module for argparse rendering - Add docs/_ext/argparse_exemplar.py extension (replaces sphinxarg.ext) - Add syntax highlighting lexers and roles for CLI documentation - Replace pretty_argparse.py with argparse_exemplar.py - Keep aafig.py extension (tmuxp-specific ASCII art rendering) - Add comprehensive test suite for all Sphinx extensions - Remove sphinx-argparse from dependencies - Update docs/conf.py to use argparse_exemplar extension - Update mypy overrides for new extension modules
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #1009 +/- ##
=======================================
Coverage 80.11% 80.11%
=======================================
Files 28 28
Lines 2409 2409
Branches 457 457
=======================================
Hits 1930 1930
Misses 356 356
Partials 123 123 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Member
Author
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. 🤖 Generated with Claude Code |
Add argparse-highlight.css with "One Dark" color palette to style the CLI usage lines with semantic colorization: - Blue: "usage:" heading - Purple: program name - Green: subcommands - Teal: options (-h, --tree) - Yellow: metavars Also strip ANSI codes and disable colors during doc builds to ensure clean parsing by the argparse lexer.
Add intro paragraphs, wrap argparse directives in `## Command` sections, and rename generic `## Usage` to descriptive section names for consistent documentation structure across projects.
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.
Summary
sphinx-argparsedependency with customsphinx_argparse_neoextensionsChanges
docs/_ext/sphinx_argparse_neo/moduledocs/_ext/argparse_exemplar.pyextensionpretty_argparse.pywith new extensionsaafig.pyextension (tmuxp-specific)sphinx-argparsefrom dependenciesTest plan
uv run ruff check . --fix --show-fixespassesuv run ruff format .passesuv run mypypassesuv run py.test --reruns 0 -vvv tests/docs/passes (298 tests)cd docs && sphinx-build -b html . _build/htmlbuilds successfully