docs: Add CLI documentation and version flag support #46

tony · 2026-01-25T13:03:41Z

Summary

Adds CLI documentation infrastructure and improves CLI usability:

CLI: g --version / g -V now shows g's version (previously passed to VCS)
Documentation: New CLI documentation page with complete command reference
Documentation: Linkable argument anchors (headerlinks) for easy sharing
Documentation: Semantic CLI markup roles and syntax highlighting

Based on tmuxp#1010 and tmuxp#1011.

User-facing changes

CLI

g --version and g -V display g's version instead of being passed to the underlying VCS
Documentation now accurately describes this behavior

Documentation

New CLI page at /cli/ with argparse-generated command reference
CLI arguments have linkable anchors (¶ headerlinks)
Improved CSS for light/dark mode compatibility

Technical changes

Added docs/_ext/sphinx_argparse_neo/ - argparse documentation with headerlinks
Added docs/_ext/argparse_lexer.py - syntax highlighting for CLI output
Added docs/_ext/argparse_roles.py - semantic markup roles (:cli-opt:, :cli-cmd:, etc.)
Added docs/_ext/argparse_exemplar.py - epilog examples transformation
Added docs/_static/css/argparse-highlight.css - CLI styling
Added comprehensive test suite in tests/docs/_ext/
Updated docs/conf.py with extension configuration
Updated pyproject.toml with mypy overrides

Test plan

References

tmuxp#1010 - Original CLI documentation infrastructure
tmuxp#1011 - Propagated improvements

Adds CLI documentation infrastructure from tmuxp#1010: - sphinx_argparse_neo extension for argparse rendering - argparse_lexer for syntax highlighting - argparse_roles for semantic CLI markup - argparse_exemplar for clean output formatting

Tests for CLI documentation extension from tmuxp#1010

Biome-formatted CSS with consolidated light mode headerlink selectors

- Add argparse_exemplar to Sphinx extensions - Add argparse-highlight.css to html_css_files - Add mypy overrides for sphinx_argparse_neo modules - Exclude tests/docs from mypy strict checking

Replace tmuxp-specific examples with inline test module creation that works in any repository without external dependencies

Add type stubs (types-docutils, types-Pygments) and configure mypy with mypy_path and explicit_package_bases for proper module resolution. - Add missing files: __init__.py, cli_usage_lexer.py, conftest.py - Fix type narrowing in directive.py (use subparser variable) - Remove redundant cast and unused type: ignore comments

codecov-commenter · 2026-01-25T14:06:08Z

Codecov Report

❌ Patch coverage is 84.41748% with 321 lines in your changes missing coverage. Please review.
✅ Project coverage is 83.71%. Comparing base (80e5695) to head (6acece6).

Files with missing lines	Patch %	Lines
docs/_ext/argparse_exemplar.py	42.40%	182 Missing ⚠️
docs/_ext/sphinx_argparse_neo/directive.py	22.53%	55 Missing ⚠️
docs/_ext/sphinx_argparse_neo/nodes.py	68.42%	48 Missing ⚠️
docs/_ext/sphinx_argparse_neo/__init__.py	38.09%	13 Missing ⚠️
docs/_ext/sphinx_argparse_neo/renderer.py	91.83%	12 Missing ⚠️
docs/_ext/sphinx_argparse_neo/compat.py	91.48%	4 Missing ⚠️
docs/_ext/sphinx_argparse_neo/parser.py	98.69%	2 Missing ⚠️
docs/_ext/argparse_roles.py	97.29%	1 Missing ⚠️
docs/_ext/conftest.py	80.00%	1 Missing ⚠️
src/g/__init__.py	93.75%	1 Missing ⚠️
... and 2 more

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #46      +/-   ##
==========================================
+ Coverage   76.24%   83.71%   +7.47%     
==========================================
  Files           5       25      +20     
  Lines         181     2235    +2054     
==========================================
+ Hits          138     1871    +1733     
- Misses         43      364     +321

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

tony · 2026-01-25T14:33:25Z

Code review

Found 2 issues:

Doctest in from_sphinx_config method contains only commented-out code instead of executable doctests (CLAUDE.md says "Doctests MUST actually execute - never comment out function calls or similar")

g/docs/_ext/argparse_exemplar.py

Lines 208 to 214 in dc4dd7c

    
                   Examples 
        
                   -------- 
        
                   This is typically called from a directive's run() method: 
        
                   >>> # In CleanArgParseDirective.run(): 
        
                   >>> # config = ExemplarConfig.from_sphinx_config(self.env.config) 
        
                   """

Overly broad mypy exclude pattern conftest\.py$ excludes ALL conftest.py files, including the root conftest.py which should be type-checked (CLAUDE.md says "Type checking is strict (mypy --strict)")

g/pyproject.toml

Lines 138 to 141 in dc4dd7c

    
           exclude = [ 
        
             "tests/docs/", 
        
             "conftest\\.py$", 
        
           ]

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

Replace commented pseudo-code with working doctest using types.SimpleNamespace to demonstrate config value extraction and default fallback behavior.

Change `conftest\.py$` to `docs/_ext/conftest\.py$` to type-check root conftest.py while avoiding duplicate module error from mypy_path config.

- Add create_parser() function to g module for documentation and --version - Create docs/cli/index.md using sphinx-argparse directive - Add cli/index to docs toctree - Support --version/-V flag in CLI

- feat(docs): Render argparse metadata as semantic definition list Replace pipe-separated format with <dl>/<dt>/<dd> structure - style(css): Use var(--code-font-size) for all argparse elements Add font-size to inline roles, pre.argparse-usage, .argparse-argument-name Add new .argparse-argument-meta flexbox styles - fix(lexer): Include underscores in lowercase metavar patterns Change [a-z][-a-z0-9]* to [a-z][-a-z0-9_]* in 6 locations - test(lexer): Add underscore metavar regression test Add fixtures and test for socket_name, config_file patterns

tony · 2026-01-25T18:12:58Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

The previous implementation used argparse's version action which calls sys.exit(), preventing run() from returning in test mode. Now version is printed manually and returns None when G_IS_TEST is set, matching the pattern used when no VCS is found. Adds tests for --version and -V flags.

The documentation previously stated "all arguments are passed directly" which was misleading since --version/-V is intercepted by g itself. Updated epilog and documentation to accurately describe this behavior.

Furo's "auto" theme follows system prefers-color-scheme. The meta tag dark styling only targeted explicit data-theme="dark", missing the auto-dark case where body:not([data-theme="light"]) applies.

The light mode override for headerlink colors used body:not([data-theme="dark"]) which incorrectly matches auto mode even when system is dark. Split into explicit light selector plus media query for auto + system light.

- CLI: g --version/-V now displays g's version - Documentation: Add CLI documentation page - Documentation: Linkable anchors for CLI arguments

Replace tmuxp-specific examples with generic "myapp" in doctests and comments.

Replace tmuxp examples in tests with generic "myapp".

tony added 5 commits January 25, 2026 07:37

tests(docs): Add sphinx_argparse_neo tests

822b465

Tests for CLI documentation extension from tmuxp#1010

style(css): Add argparse-highlight CSS

3c17d2f

Biome-formatted CSS with consolidated light mode headerlink selectors

build(docs): Configure argparse_exemplar extension

cbdc962

- Add argparse_exemplar to Sphinx extensions - Add argparse-highlight.css to html_css_files - Add mypy overrides for sphinx_argparse_neo modules - Exclude tests/docs from mypy strict checking

fix(docs): Use repo-agnostic examples in compat.py doctests

f89e457

Replace tmuxp-specific examples with inline test module creation that works in any repository without external dependencies

tony force-pushed the more-cli-docs branch from 4265442 to f89e457 Compare January 25, 2026 13:37

tony added 5 commits January 25, 2026 08:41

fix(docs): Add executable doctest for ExemplarConfig.from_sphinx_config

32a3be3

Replace commented pseudo-code with working doctest using types.SimpleNamespace to demonstrate config value extraction and default fallback behavior.

build(mypy): Type-check root conftest.py by narrowing exclude pattern

74fed7f

Change `conftest\.py$` to `docs/_ext/conftest\.py$` to type-check root conftest.py while avoiding duplicate module error from mypy_path config.

docs(cli): Add CLI documentation page with argparse output

27674f8

- Add create_parser() function to g module for documentation and --version - Create docs/cli/index.md using sphinx-argparse directive - Add cli/index to docs toctree - Support --version/-V flag in CLI

style: Fix line too long in CLI description

69f8c1f

tony added 6 commits January 25, 2026 12:17

style(tests): Add missing future annotations imports

8033764

docs: Clarify that --version/-V is handled by g

0f50411

The documentation previously stated "all arguments are passed directly" which was misleading since --version/-V is intercepted by g itself. Updated epilog and documentation to accurately describe this behavior.

fix(css): Handle system auto-dark mode for argparse-meta-tag

5cf2c8e

Furo's "auto" theme follows system prefers-color-scheme. The meta tag dark styling only targeted explicit data-theme="dark", missing the auto-dark case where body:not([data-theme="light"]) applies.

fix(css): Handle system auto-light mode for headerlink colors

7ae3ac8

The light mode override for headerlink colors used body:not([data-theme="dark"]) which incorrectly matches auto mode even when system is dark. Split into explicit light selector plus media query for auto + system light.

docs(changelog): Add 0.0.10 release notes

6cdd947

- CLI: g --version/-V now displays g's version - Documentation: Add CLI documentation page - Documentation: Linkable anchors for CLI arguments

tony changed the title ~~docs: Add CLI documentation infrastructure from tmuxp#1010~~ docs: Add CLI documentation and version flag support Jan 25, 2026

tony added 2 commits January 25, 2026 13:13

docs(sphinx-ext): Use generic examples in docstrings

8c0d6f8

Replace tmuxp-specific examples with generic "myapp" in doctests and comments.

docs: Remove remaining tmuxp-specific references

6acece6

Replace tmuxp examples in tests with generic "myapp".

tony merged commit a5ebb45 into master Jan 25, 2026
8 checks passed

tony deleted the more-cli-docs branch January 25, 2026 19:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: Add CLI documentation and version flag support #46

docs: Add CLI documentation and version flag support #46

Uh oh!

tony commented Jan 25, 2026 •

edited

Loading

Uh oh!

codecov-commenter commented Jan 25, 2026 •

edited

Loading

Uh oh!

tony commented Jan 25, 2026

Uh oh!

tony commented Jan 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

docs: Add CLI documentation and version flag support #46

docs: Add CLI documentation and version flag support #46

Uh oh!

Conversation

tony commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

User-facing changes

CLI

Documentation

Technical changes

Test plan

References

Uh oh!

codecov-commenter commented Jan 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

tony commented Jan 25, 2026

Code review

Uh oh!

tony commented Jan 25, 2026

Code review

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tony commented Jan 25, 2026 •

edited

Loading

codecov-commenter commented Jan 25, 2026 •

edited

Loading