sphinx-autodoc-argparse 0.0.1a8__tar.gz

sphinx_autodoc_argparse-0.0.1a8/.gitignore

@@ -0,0 +1,228 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Generated by sphinx_fonts extension (downloaded at build time)
+docs/_static/fonts/
+docs/_static/css/fonts.css
+
+# Claude Code
+**/CLAUDE.local.md
+**/CLAUDE.*.md
+**/.claude/settings.local.json
+
+# Playwright MCP
+.playwright-mcp/
+
+# Repo-local pytest mirror (do not track — validator-only)
+out/
+
+# Misc
+.vim/
+*.lprof
+pip-wheel-metadata/
+monkeytype.sqlite3

sphinx_autodoc_argparse-0.0.1a8/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: sphinx-autodoc-argparse
+Version: 0.0.1a8
+Summary: Modern Sphinx extension for documenting argparse-based CLI tools
+Project-URL: Repository, https://github.com/git-pull/gp-sphinx
+Author-email: Tony Narlock <tony@git-pull.com>
+License: MIT
+Keywords: argparse,cli,documentation,sphinx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Sphinx
+Classifier: Framework :: Sphinx :: Domain
+Classifier: Framework :: Sphinx :: Extension
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Documentation :: Sphinx
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+Requires-Python: <4.0,>=3.10
+Requires-Dist: docutils
+Requires-Dist: pygments
+Requires-Dist: sphinx>=8.1
+Description-Content-Type: text/markdown
+
+# sphinx-autodoc-argparse
+
+Modern Sphinx extension for documenting argparse-based CLI tools.
+
+A modernized replacement for `sphinx-argparse` that:
+- Works with Sphinx 8.x and 9.x (no `autodoc.mock` dependency)
+- Fixes long-standing issues (TOC pollution, heading levels)
+- Provides configurable output (rubrics vs sections, flattened subcommands)
+- Includes Pygments lexers for argparse help output and CLI usage blocks
+- Supports extensibility via renderer classes
+
+## Install
+
+```console
+$ pip install sphinx-autodoc-argparse
+```
+
+## Usage
+
+In your `docs/conf.py`:
+
+```python
+extensions = ["sphinx_autodoc_argparse"]
+```
+
+Then use the `.. argparse::` directive:
+
+```rst
+.. argparse::
+   :module: myapp.cli
+   :func: create_parser
+   :prog: myapp
+```

sphinx_autodoc_argparse-0.0.1a8/README.md

@@ -0,0 +1,33 @@
+# sphinx-autodoc-argparse
+
+Modern Sphinx extension for documenting argparse-based CLI tools.
+
+A modernized replacement for `sphinx-argparse` that:
+- Works with Sphinx 8.x and 9.x (no `autodoc.mock` dependency)
+- Fixes long-standing issues (TOC pollution, heading levels)
+- Provides configurable output (rubrics vs sections, flattened subcommands)
+- Includes Pygments lexers for argparse help output and CLI usage blocks
+- Supports extensibility via renderer classes
+
+## Install
+
+```console
+$ pip install sphinx-autodoc-argparse
+```
+
+## Usage
+
+In your `docs/conf.py`:
+
+```python
+extensions = ["sphinx_autodoc_argparse"]
+```
+
+Then use the `.. argparse::` directive:
+
+```rst
+.. argparse::
+   :module: myapp.cli
+   :func: create_parser
+   :prog: myapp
+```

sphinx_autodoc_argparse-0.0.1a8/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "sphinx-autodoc-argparse"
+version = "0.0.1a8"
+description = "Modern Sphinx extension for documenting argparse-based CLI tools"
+requires-python = ">=3.10,<4.0"
+authors = [
+  {name = "Tony Narlock", email = "tony@git-pull.com"}
+]
+license = { text = "MIT" }
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Framework :: Sphinx",
+  "Framework :: Sphinx :: Domain",
+  "Framework :: Sphinx :: Extension",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Documentation",
+  "Topic :: Documentation :: Sphinx",
+  "Topic :: Software Development :: Documentation",
+  "Typing :: Typed",
+]
+readme = "README.md"
+keywords = ["sphinx", "argparse", "cli", "documentation"]
+dependencies = [
+  "sphinx>=8.1",
+  "pygments",
+  "docutils",
+]
+
+[project.urls]
+Repository = "https://github.com/git-pull/gp-sphinx"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sphinx_autodoc_argparse"]

sphinx_autodoc_argparse-0.0.1a8/src/sphinx_autodoc_argparse/__init__.py

@@ -0,0 +1,137 @@
+"""sphinx_autodoc_argparse - Modern sphinx-argparse replacement.
+
+A Sphinx extension for documenting argparse-based CLI tools that:
+- Works with Sphinx 8.x AND 9.x (no autodoc.mock dependency)
+- Fixes long-standing sphinx-argparse issues (TOC pollution, heading levels)
+- Provides configurable output (rubrics vs sections, flattened subcommands)
+- Supports extensibility via renderer classes
+- Text processing utilities (ANSI stripping)
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+from sphinx_autodoc_argparse.directive import ArgparseDirective
+from sphinx_autodoc_argparse.domain import ArgparseDomain
+from sphinx_autodoc_argparse.nodes import (
+    argparse_argument,
+    argparse_group,
+    argparse_program,
+    argparse_subcommand,
+    argparse_subcommands,
+    argparse_usage,
+    depart_argparse_argument_html,
+    depart_argparse_group_html,
+    depart_argparse_program_html,
+    depart_argparse_subcommand_html,
+    depart_argparse_subcommands_html,
+    depart_argparse_usage_html,
+    visit_argparse_argument_html,
+    visit_argparse_group_html,
+    visit_argparse_program_html,
+    visit_argparse_subcommand_html,
+    visit_argparse_subcommands_html,
+    visit_argparse_usage_html,
+)
+from sphinx_autodoc_argparse.utils import strip_ansi
+
+__all__ = [
+    "ArgparseDirective",
+    "strip_ansi",
+]
+
+if t.TYPE_CHECKING:
+    from sphinx.application import Sphinx
+
+__version__ = "0.0.1a8"
+
+
+class SetupDict(t.TypedDict):
+    """Return type for Sphinx extension setup()."""
+
+    version: str
+    parallel_read_safe: bool
+    parallel_write_safe: bool
+
+
+def setup(app: Sphinx) -> SetupDict:
+    """Register the argparse directive and configuration options.
+
+    Parameters
+    ----------
+    app : Sphinx
+        The Sphinx application object.
+
+    Returns
+    -------
+    SetupDict
+        Extension metadata.
+    """
+    # Configuration options
+    app.add_config_value(
+        "argparse_group_title_prefix",
+        "",
+        "html",
+        description="Prefix for argument group titles",
+    )
+    app.add_config_value(
+        "argparse_show_defaults",
+        True,
+        "html",
+        description="Show default values in argument docs",
+    )
+    app.add_config_value(
+        "argparse_show_choices",
+        True,
+        "html",
+        description="Show choice constraints",
+    )
+    app.add_config_value(
+        "argparse_show_types",
+        True,
+        "html",
+        description="Show type information",
+    )
+
+    # Register custom nodes
+    app.add_node(
+        argparse_program,
+        html=(visit_argparse_program_html, depart_argparse_program_html),
+    )
+    app.add_node(
+        argparse_usage,
+        html=(visit_argparse_usage_html, depart_argparse_usage_html),
+    )
+    app.add_node(
+        argparse_group,
+        html=(visit_argparse_group_html, depart_argparse_group_html),
+    )
+    app.add_node(
+        argparse_argument,
+        html=(visit_argparse_argument_html, depart_argparse_argument_html),
+    )
+    app.add_node(
+        argparse_subcommands,
+        html=(visit_argparse_subcommands_html, depart_argparse_subcommands_html),
+    )
+    app.add_node(
+        argparse_subcommand,
+        html=(visit_argparse_subcommand_html, depart_argparse_subcommand_html),
+    )
+
+    # Register the argparse domain so :argparse:program: / :argparse:option: /
+    # :argparse:subcommand: / :argparse:positional: xrefs resolve and the two
+    # auto-generated indices (argparse-programsindex, argparse-optionsindex)
+    # are available.  The renderer populates this domain via note_* helpers
+    # in parallel with the existing std:cmdoption emission.
+    app.add_domain(ArgparseDomain)
+
+    # Register directive
+    app.add_directive("argparse", ArgparseDirective)
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

sphinx_autodoc_argparse-0.0.1a8/src/sphinx_autodoc_argparse/cli_usage_lexer.py

@@ -0,0 +1,120 @@
+"""Pygments lexer for CLI usage/help output.
+
+This module provides a custom Pygments lexer for highlighting command-line
+usage text typically generated by argparse, getopt, or similar libraries.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+from pygments.lexer import RegexLexer, bygroups as _bygroups, include
+from pygments.token import Generic, Name, Operator, Punctuation, Text, Whitespace
+
+# Wrapper to silence mypy [no-untyped-call] - bygroups is untyped in types-pygments
+bygroups: t.Callable[..., t.Any] = _bygroups
+
+
+class CLIUsageLexer(RegexLexer):
+    """Lexer for CLI usage/help text (argparse, etc.).
+
+    Highlights usage patterns including options, arguments, and meta-variables.
+
+    Examples
+    --------
+    >>> from pygments.token import Token
+    >>> lexer = CLIUsageLexer()
+    >>> tokens = list(lexer.get_tokens("usage: cmd [-h]"))
+    >>> tokens[0]
+    (Token.Generic.Heading, 'usage:')
+    >>> tokens[2]
+    (Token.Name.Label, 'cmd')
+    """
+
+    name = "CLI Usage"
+    aliases = ["cli-usage", "usage"]  # noqa: RUF012
+    filenames: t.ClassVar[list[str]] = []
+    mimetypes = ["text/x-cli-usage"]  # noqa: RUF012
+
+    tokens = {  # noqa: RUF012
+        "root": [
+            # "usage:" at start of line
+            (r"^(usage:)(\s+)", bygroups(Generic.Heading, Whitespace)),
+            # Continuation lines (leading whitespace for wrapped usage)
+            (r"^(\s+)(?=\S)", Whitespace),
+            include("inline"),
+        ],
+        "inline": [
+            # Whitespace
+            (r"\s+", Whitespace),
+            # Long options with = value (e.g., --log-level=VALUE)
+            (
+                r"(--[a-zA-Z0-9][-a-zA-Z0-9]*)(=)([A-Z][A-Z0-9_]*|[a-z][-a-z0-9]*)",
+                bygroups(Name.Tag, Operator, Name.Variable),
+            ),
+            # Long options standalone
+            (r"--[a-zA-Z0-9][-a-zA-Z0-9]*", Name.Tag),
+            # Short options with space-separated value (e.g., -S socket-path)
+            (
+                r"(-[a-zA-Z0-9])(\s+)([A-Z][A-Z0-9_]*|[a-z][-a-z0-9]*)",
+                bygroups(Name.Attribute, Whitespace, Name.Variable),
+            ),
+            # Short options standalone
+            (r"-[a-zA-Z0-9]", Name.Attribute),
+            # UPPERCASE meta-variables (COMMAND, FILE, PATH)
+            (r"\b[A-Z][A-Z0-9_]+\b", Name.Constant),
+            # Opening bracket - enter optional state
+            (r"\[", Punctuation, "optional"),
+            # Closing bracket (fallback for unmatched)
+            (r"\]", Punctuation),
+            # Choice separator (pipe)
+            (r"\|", Operator),
+            # Parentheses for grouping
+            (r"[()]", Punctuation),
+            # Positional/command names (lowercase with dashes)
+            (r"\b[a-z][-a-z0-9]*\b", Name.Label),
+            # Catch-all for any other text
+            (r"[^\s\[\]|()]+", Text),
+        ],
+        "optional": [
+            # Nested optional bracket
+            (r"\[", Punctuation, "#push"),
+            # End optional
+            (r"\]", Punctuation, "#pop"),
+            # Contents use inline rules
+            include("inline"),
+        ],
+    }
+
+
+def tokenize_usage(text: str) -> list[tuple[str, str]]:
+    """Tokenize usage text and return list of (token_type, value) tuples.
+
+    Parameters
+    ----------
+    text : str
+        CLI usage text to tokenize.
+
+    Returns
+    -------
+    list[tuple[str, str]]
+        List of (token_type_name, text_value) tuples.
+
+    Examples
+    --------
+    >>> result = tokenize_usage("usage: cmd [-h]")
+    >>> result[0]
+    ('Token.Generic.Heading', 'usage:')
+    >>> result[2]
+    ('Token.Name.Label', 'cmd')
+    >>> result[4]
+    ('Token.Punctuation', '[')
+    >>> result[5]
+    ('Token.Name.Attribute', '-h')
+    >>> result[6]
+    ('Token.Punctuation', ']')
+    """
+    lexer = CLIUsageLexer()
+    return [
+        (str(tok_type), tok_value) for tok_type, tok_value in lexer.get_tokens(text)
+    ]