docs(_ext): Add Sphinx extensions for CLI documentation

[tony]

Summary

• Port CLI documentation extensions from tmuxp v1.63.0
• Add custom Pygments lexer for CLI usage syntax highlighting
• Add enhanced sphinx-argparse wrapper with ANSI stripping and examples transformation
• Include comprehensive test suite (88 tests)

Changes

Commit 1: Sphinx extensions and tests

• docs/_ext/cli_usage_lexer.py - Pygments lexer for CLI usage patterns
• docs/_ext/pretty_argparse.py - Enhanced sphinx-argparse directive
• tests/docs/_ext/ - Comprehensive test suite adapted for vcspull

Commit 2: Type stubs

• Add types-docutils and types-Pygments to dependencies

Commit 3: Coverage config

• Exclude docs/_ext/* from coverage reporting

Test plan

• All 401 tests pass (uv run py.test --reruns 0 -vvv)
• Ruff linting passes
• Mypy type checking passes
• Build docs and verify CLI pages render correctly

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80.52%. Comparing base (b523f6b) to head (0de58df).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #496      +/-   ##
==========================================
+ Coverage   80.42%   80.52%   +0.09%     
==========================================
  Files          16       16              
  Lines        2192     2192              
  Branches      454      454              
==========================================
+ Hits         1763     1765       +2     
+ Misses        278      277       -1     
+ Partials      151      150       -1     

☔ 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

Found 2 issues:

1. Import style violation - CLAUDE.md says "Use namespace imports: import enum instead of from enum import Enum". The new files use from ... import ... style extensively (e.g., from pygments.lexer import RegexLexer, from docutils import nodes).

vcspull/docs/_ext/cli_usage_lexer.py

Lines 8 to 18 in 50119d3

	from pygments.lexer import RegexLexer, bygroups, include
	from pygments.token import Generic, Name, Operator, Punctuation, Text, Whitespace
	class CLIUsageLexer(RegexLexer):
	"""Lexer for CLI usage/help text (argparse, etc.).
	Highlights usage patterns including options, arguments, and meta-variables.
	Examples

2. Duplicate Sphinx labels - The make_section_id() function generates identical "examples" IDs across all CLI documentation pages, causing 6 Sphinx warnings during just build-docs. The function has a counter parameter for uniqueness but it's always called with counter=0.

vcspull/docs/_ext/pretty_argparse.py

Lines 137 to 193 in 50119d3

	def make_section_id(
	term_text: str, counter: int = 0, *, is_subsection: bool = False
	) -> str:
	"""Generate a section ID from an examples term.
	Parameters
	----------
	term_text : str
	The examples term text (e.g., "Machine-readable output: examples:")
	counter : int
	Counter for uniqueness if multiple examples sections exist.
	is_subsection : bool
	If True, omit "-examples" suffix for cleaner nested IDs.
	Returns
	-------
	str
	A normalized section ID.
	Examples
	--------
	>>> make_section_id("examples:")
	'examples'
	>>> make_section_id("Machine-readable output examples:")
	'machine-readable-output-examples'
	>>> make_section_id("Field-scoped examples:", is_subsection=True)
	'field-scoped'
	>>> make_section_id("examples:", counter=1)
	'examples-1'
	"""
	# Extract prefix before "examples" (e.g., "Machine-readable output")
	lower_text = term_text.lower().rstrip(":")
	if "examples" in lower_text:
	prefix = lower_text.rsplit("examples", 1)[0].strip()
	# Remove trailing colon from prefix (handles ": examples" pattern)
	prefix = prefix.rstrip(":").strip()
	if prefix:
	normalized_prefix = prefix.replace(" ", "-")
	# Subsections don't need "-examples" suffix
	if is_subsection:
	section_id = normalized_prefix
	else:
	section_id = f"{normalized_prefix}-examples"
	else:
	section_id = "examples"
	else:
	section_id = "examples"
	# Add counter suffix for uniqueness
	if counter > 0:
	section_id = f"{section_id}-{counter}"
	return section_id
	def make_section_title(term_text: str, *, is_subsection: bool = False) -> str:

Generated with Claude Code

_{- If this code review was useful, please react with a thumbs up. Otherwise, react with a thumbs down.}

[tony]

Correction to issue #1: The import style concern was over-applied. The CLAUDE.md examples (import enum, import typing as t) target stdlib imports. The flagged imports are all third-party packages (pygments, docutils, sphinxarg) where direct imports are idiomatic - especially for Pygments token types in lexers.

Issue #1 is withdrawn. Only issue #2 (duplicate Sphinx labels) remains valid.