docs(cli) Custom argparse documentation engine with syntax highlighting

[tony]

Summary

Replace external sphinx-argparse dependency with custom sphinx_argparse_neo extensions, ported from vcspull project. Adds comprehensive documentation infrastructure for CLI commands.

Changes

New Extensions

• docs/_ext/sphinx_argparse_neo/ - Complete argparse documentation engine
• docs/_ext/argparse_exemplar.py - Transforms epilog examples into TOC sections
• docs/_ext/argparse_lexer.py - Pygments lexers for CLI syntax highlighting
• docs/_ext/argparse_roles.py - RST roles for inline CLI formatting
• docs/_static/css/argparse-highlight.css - Styling for usage blocks and code

Bug Fixes

• Use slice assignment for docutils node children manipulation (fixes parent tracking)
• Add type annotation to fix mypy no-any-return error
• Escape asterisks in glob patterns to prevent RST emphasis warnings
• Add ID prefix to avoid duplicate section IDs across subcommand pages

Documentation

• Restructure CLI command pages to match vcspull pattern
• Add doctest exceptions to AGENTS.md for Sphinx visitor patterns
• Add doctests to _create_example_section() and _extract_mutex_groups()

Removed

• pretty_argparse.py (replaced by new extensions)
• sphinx-argparse dependency

Test plan

• uv run ruff check . --fix --show-fixes passes
• uv run ruff format . passes
• uv run mypy passes
• uv run py.test passes (997 tests, 313 for docs/_ext)
• cd docs && sphinx-build -b html . _build/html builds successfully

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.11%. Comparing base (917dcd5) to head (2d80f70).
⚠️ Report is 15 commits behind head on master.

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.
📢 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]

Code review

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

🤖 Generated with Claude Code

[tony]

Code review

Found 1 issue:

1. Missing required doctests in sphinx_argparse_neo functions. CLAUDE.md states "All functions and methods MUST have working doctests. Doctests serve as both documentation and tests." Multiple functions in the new extension have complete docstrings with Parameters/Returns sections but lack the required Examples section with working doctests.

Affected files include:

• docs/_ext/sphinx_argparse_neo/nodes.py - 12 HTML visitor/depart functions (lines 310-553)
• docs/_ext/sphinx_argparse_neo/renderer.py - create_renderer() function (lines 499-521)
• docs/_ext/sphinx_argparse_neo/parser.py - _extract_mutex_groups() function

Example of a function missing doctests:

tmuxp/docs/_ext/sphinx_argparse_neo/nodes.py

Lines 310 to 322 in f879f92

	def visit_argparse_program_html(self: HTML5Translator, node: argparse_program) -> None:
	"""Visit argparse_program node - start program container.
	Parameters
	----------
	self : HTML5Translator
	The Sphinx HTML translator.
	node : argparse_program
	The program node being visited.
	"""
	prog = node.get("prog", "")
	self.body.append(f'<div class="argparse-program" data-prog="{prog}">\n')

tmuxp/docs/_ext/sphinx_argparse_neo/renderer.py

Lines 499 to 521 in f879f92

	def create_renderer(
	config: RenderConfig | None = None,
	state: RSTState | None = None,
	renderer_class: type[ArgparseRenderer] | None = None,
	) -> ArgparseRenderer:
	"""Create a renderer instance.
	Parameters
	----------
	config : RenderConfig | None
	Rendering configuration.
	state : RSTState | None
	RST state for parsing.
	renderer_class : type[ArgparseRenderer] | None
	Custom renderer class to use.
	Returns
	-------
	ArgparseRenderer
	Configured renderer instance.
	"""
	cls = renderer_class or ArgparseRenderer
	return cls(config=config, state=state)

🤖 Generated with Claude Code

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

[tony]

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 👎.}