sphinx_argparse_neo w/ sphinx 9 #500
Open
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: Enhanced CLI documentation with syntax highlighting and ANSI stripping what: - Add cli_usage_lexer.py: Pygments lexer for CLI usage patterns - Add pretty_argparse.py: Enhanced sphinx-argparse wrapper - Add comprehensive tests for both extensions (88 tests) - Update docs/conf.py to register pretty_argparse extension - Update pyproject.toml with mypy overrides and doctest config - Fix pre-existing doctest issue in config_reader.py
why: Type stubs for docutils and Pygments libraries used in docs extensions what: - Add types-docutils to dev and typings groups - Add types-Pygments to dev and typings groups
why: Sphinx extensions are documentation utilities, not core code what: - Add docs/_ext/* to coverage.run.omit
why: CLI examples from --help weren't appearing in generated docs what: - Remove :nodescription: from all CLI argparse directives - Allows sphinx-argparse to include description with examples - pretty_argparse transforms examples into proper sections
…ions
why: Asterisks in patterns like "django-*" trigger docutils emphasis
parsing warnings when sphinx-argparse renders help text as RST
what:
- Add escape_rst_emphasis() to escape asterisks preceded by delimiters
- Override _nested_parse_paragraph() to pre-escape descriptions
- Fixes "Inline emphasis start-string without end-string" warnings
why: Ensure RST emphasis escaping works correctly for argparse patterns what: - Add 13 parameterized test cases covering: - Glob patterns like "django-*" are escaped - Multiple patterns in one string - Already escaped patterns unchanged - Valid emphasis (*text*) unchanged - Various edge cases (empty, underscore, dot)
why: Documentation code blocks showing vcspull CLI output need semantic highlighting to match the colors used in the actual CLI. what: - Create vcspull_output_lexer.py with VcspullOutputLexer RegexLexer - Map semantic colors to Pygments tokens (SUCCESS→Generic.Inserted, WARNING→Name.Exception, ERROR→Generic.Error, INFO→Name.Function) - Handle list, status, sync, summary outputs and workspace headers - Register lexer with Sphinx in pretty_argparse.py setup() - Add 17 parameterized tests for all output patterns
… import why: mypy cannot resolve sibling module imports in docs/_ext/ directory. what: - Add type: ignore[import-not-found] to vcspull_output_lexer import
why: Console code blocks use BashSessionLexer which hardcodes output as Generic.Output, losing semantic highlighting for vcspull command output. what: - Create vcspull_console_lexer.py extending ShellSessionBaseLexer pattern - Delegate output lines to VcspullOutputLexer for semantic coloring - Register as 'vcspull-console' alias in pretty_argparse.py - Update docs/cli/list.md to use vcspull-console for output blocks - Add 8 tests for console session tokenization
why: mypy reports errors for missing type stubs and return type annotation. what: - Add type: ignore[attr-defined] for do_insertions and line_re imports - Add type: ignore[no-untyped-def] for generator method - Remove explicit type annotations that conflict with Pygments internals
why: Plain HTTPS URLs in parentheses were incorrectly tokenized as repo names, and interactive prompts like [y/N] had no special highlighting. what: - Add pattern for plain HTTPS/HTTP URLs (Name.Tag) - Add pattern for interactive prompt options [y/N] (Comment) - Add pattern for question mark prompt indicator (Generic.Prompt) - Add 3 tests for new patterns
Update CLI documentation to use vcspull-console lexer for code blocks that display vcspull command output with bullets, checkmarks, and other semantic symbols. Files updated: - discover.md: basic usage, unattended mode, dry run, warnings, existing entries - status.md: basic usage, filtering, detailed status - sync.md: dry run, error handling - search.md: basic usage, field-scoped queries
…highlighting why: Generic "name:" pattern matched false positives like "add:" in "Would add:" and "complete:" in "Dry run complete:". what: - Remove generic "name:" pattern that caused false positives - Add ":" to success symbol lookahead for "✓ repo:" status output - Add vcspull command and subcommand highlighting (Name.Builtin) - Add more labels: Remote:, Repository:, Note:, Usage: - Use vcspull-output for pure output blocks in discover.md
why: The namespace import guideline was being misapplied to third-party packages like pygments, where direct imports are idiomatic. what: - Clarify that namespace imports apply to standard library modules - Add explicit note that third-party packages use idiomatic styles - Reorganize section with clear headers for each rule
why: The make_section_id() function generated identical "examples" IDs across all CLI documentation pages, causing 6 Sphinx duplicate label warnings during docs build. what: - Add page_prefix parameter to make_section_id() for cross-page uniqueness - Thread page_prefix through _create_example_section(), transform_definition_list() - Extract docname in CleanArgParseDirective.run() and pass to process_node() - Section IDs now include page name: "sync-examples", "add-examples", etc. - Add test for page_prefix functionality
why: sphinx-argparse broke with Sphinx 9.x due to internal API changes.
Creating a local replacement with better architecture.
what:
- Add parser.py with dataclasses for argparse introspection
- Add nodes.py with custom docutils node types and HTML visitors
- Add renderer.py with configurable ParserInfo to nodes conversion
- Add directive.py with SphinxDirective implementation
- Add compat.py with module import and mock handling
- Add myst.py with optional MyST markdown support
- Support sphinx-argparse compatibility options (nosubcommands, etc.)
why: Ensure the new extension works correctly with full coverage. what: - Add conftest.py with shared pytest fixtures for parser factories - Add test_parser.py with 50+ tests for argparse introspection - Add test_nodes.py with node creation and nesting tests - Add test_renderer.py with configuration and output tests - Add test_compat.py with mock module and import tests - Add test_myst.py with format detection and parsing tests
why: Remove dependency on external sphinx-argparse package.
what:
- Change base class from sphinxarg.ext.ArgParseDirective to
sphinx_argparse_neo.directive.ArgparseDirective
- Update setup() to call app.setup_extension("sphinx_argparse_neo")
- Maintain all existing transformations (ANSI stripping, examples)
why: Extension is now loaded via pretty_argparse which uses sphinx_argparse_neo. what: - Remove "sphinxarg.ext" from extensions list - pretty_argparse now handles extension chain setup
why: Replaced with local sphinx_argparse_neo extension. what: - Remove "sphinx-argparse" from dev dependency group - Remove "sphinx-argparse" from docs dependency group
why: Local extension modules need to be in mypy ignore list. what: - Replace "sphinxarg.*" with "sphinx_argparse_neo" and "sphinx_argparse_neo.*"
why: Enable syntax highlighting for argparse help output and inline CLI elements in documentation, improving readability of command-line examples. what: - Add ArgparseUsageLexer, ArgparseHelpLexer, ArgparseLexer for code blocks - Add CLI inline roles (cli-option, cli-metavar, cli-command, etc.) - Add CSS styling with Furo theme variable support - Register lexers and roles in pretty_argparse.py setup() - Fix critical bugs: token dict sharing, infinite loops, state transitions
why: The argparse directive was outputting raw text without semantic highlighting, while the CSS targeted Pygments classes that weren't used. what: - Add _token_to_css_class helper to map Pygments tokens to CSS classes - Add _highlight_usage to tokenize usage text with ArgparseUsageLexer - Add _highlight_argument_names for option/metavar highlighting - Update visit_argparse_usage_html to emit highlighted spans - Update visit_argparse_argument_html to highlight argument signatures - Add CSS selectors for .argparse-usage and .argparse-argument-name
why: sphinx_argparse_neo works with Sphinx 9.x, no longer need cap. what: - Change "sphinx<9" to "sphinx>=8" in dev dependency group - Change "sphinx<9" to "sphinx>=8" in docs dependency group
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.
sphinx 9 is tricky because it's python 3.12+, https://www.sphinx-doc.org/en/master/internals/release-process.html#python-version-support-policy
We would need our mypy / build system isn't running into: