From b6b9614316494233aeaf545e6c83d78e0c671495 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 29 Mar 2026 09:31:26 -0500 Subject: [PATCH 1/7] docs(deps[gp-sphinx]): Migrate to gp-sphinx workspace packages (editable) why: gp-sphinx consolidates the docs configuration, extensions, theme, and font setup that was duplicated across 14+ git-pull projects. This migration replaces ~5500 lines of local copies and manual conf.py boilerplate with a single merge_sphinx_config() call backed by 4 local editable packages. what: - pyproject.toml: Replace furo, sphinx-autodoc-typehints, sphinx-inline-tabs, sphinxext-opengraph, sphinx-copybutton, sphinxext-rediraffe, sphinx-design, myst-parser, linkify-it-py with gp-sphinx + sphinx-argparse-neo. Add [tool.uv.sources] pointing to local gp-sphinx packages as editable installs - docs/conf.py: Rewrite 293-line manual config to 46-line merge_sphinx_config() call; use make_linkcode_resolve() for linkcode; theme switches to sphinx-gptheme (Furo child); spa-nav.js/tabs.js workarounds handled by gp-sphinx setup(); fonts/copybutton/myst/OGP all from defaults - docs/_ext/: Remove sphinx_fonts.py, argparse_exemplar.py, argparse_lexer.py, argparse_roles.py, cli_usage_lexer.py, sphinx_argparse_neo/ (all now in published packages); keep aafig.py (tmuxp-specific) - docs/_static/js/spa-nav.js: Remove (now bundled in sphinx-gptheme theme) - tests/docs/_ext/: Update imports from old _ext/ paths to sphinx_argparse_neo.* package paths; remove sys.path manipulation from conftest.py; fix version assertion in test_sphinx_fonts.py to use __version__ instead of "1.0" --- docs/_ext/argparse_exemplar.py | 1305 -------------------- docs/_ext/argparse_lexer.py | 429 ------- docs/_ext/argparse_roles.py | 370 ------ docs/_ext/cli_usage_lexer.py | 115 -- docs/_ext/sphinx_argparse_neo/__init__.py | 101 -- docs/_ext/sphinx_argparse_neo/compat.py | 271 ---- docs/_ext/sphinx_argparse_neo/directive.py | 240 ---- docs/_ext/sphinx_argparse_neo/nodes.py | 647 ---------- docs/_ext/sphinx_argparse_neo/parser.py | 659 ---------- docs/_ext/sphinx_argparse_neo/renderer.py | 604 --------- docs/_ext/sphinx_argparse_neo/utils.py | 78 -- docs/_ext/sphinx_fonts.py | 153 --- docs/_static/js/spa-nav.js | 254 ---- docs/conf.py | 300 +---- pyproject.toml | 33 +- tests/docs/_ext/conftest.py | 8 - tests/docs/_ext/test_argparse_exemplar.py | 4 +- tests/docs/_ext/test_argparse_lexer.py | 2 +- tests/docs/_ext/test_argparse_roles.py | 4 +- tests/docs/_ext/test_cli_usage_lexer.py | 2 +- tests/docs/_ext/test_sphinx_fonts.py | 2 +- uv.lock | 140 ++- 22 files changed, 137 insertions(+), 5584 deletions(-) delete mode 100644 docs/_ext/argparse_exemplar.py delete mode 100644 docs/_ext/argparse_lexer.py delete mode 100644 docs/_ext/argparse_roles.py delete mode 100644 docs/_ext/cli_usage_lexer.py delete mode 100644 docs/_ext/sphinx_argparse_neo/__init__.py delete mode 100644 docs/_ext/sphinx_argparse_neo/compat.py delete mode 100644 docs/_ext/sphinx_argparse_neo/directive.py delete mode 100644 docs/_ext/sphinx_argparse_neo/nodes.py delete mode 100644 docs/_ext/sphinx_argparse_neo/parser.py delete mode 100644 docs/_ext/sphinx_argparse_neo/renderer.py delete mode 100644 docs/_ext/sphinx_argparse_neo/utils.py delete mode 100644 docs/_ext/sphinx_fonts.py delete mode 100644 docs/_static/js/spa-nav.js diff --git a/docs/_ext/argparse_exemplar.py b/docs/_ext/argparse_exemplar.py deleted file mode 100644 index a4a7e1fc8b..0000000000 --- a/docs/_ext/argparse_exemplar.py +++ /dev/null @@ -1,1305 +0,0 @@ -"""Transform argparse epilog "examples:" definition lists into documentation sections. - -This Sphinx extension post-processes sphinx_argparse_neo output to convert -specially-formatted "examples:" definition lists in argparse epilogs into -proper documentation sections with syntax-highlighted code blocks. - -The extension is designed to be generic and reusable across different projects. -All behavior can be customized via Sphinx configuration options. - -Purpose -------- -When documenting CLI tools with argparse, it's useful to include examples in -the epilog. This extension recognizes a specific definition list format and -transforms it into structured documentation sections that appear in the TOC. - -Input Format ------------- -Format your argparse epilog with definition lists where terms end with "examples:": - -.. code-block:: python - - parser = argparse.ArgumentParser( - epilog=textwrap.dedent(''' - examples: - myapp sync - myapp sync myrepo - - Machine-readable output examples: - myapp sync --json - myapp sync -F json myrepo - '''), - formatter_class=argparse.RawDescriptionHelpFormatter, - ) - -The epilog text will be parsed as a definition list by docutils, with: -- Terms: "examples:", "Machine-readable output examples:", etc. -- Definitions: The example commands (one per line) - -Output ------- -The extension transforms these into proper sections: - -- A base "examples:" term creates an "Examples" section -- Category-prefixed terms like "Machine-readable output examples:" create - subsections nested under the parent Examples section -- Each command line becomes a syntax-highlighted console code block - -Configuration -------------- -Configure via conf.py. All options have sensible defaults. - -**Term Detection:** - -``argparse_examples_term_suffix`` : str (default: "examples") - Term must end with this string to be treated as an examples header. - -``argparse_examples_base_term`` : str (default: "examples") - Exact match for the base examples section (case-insensitive). - -``argparse_examples_section_title`` : str (default: "Examples") - Title used for the base examples section. - -**Usage Detection:** - -``argparse_usage_pattern`` : str (default: "usage:") - Text must start with this to be treated as a usage block (case-insensitive). - -**Code Block Formatting:** - -``argparse_examples_command_prefix`` : str (default: "$ ") - Prefix added to each command line in examples code blocks. - -``argparse_examples_code_language`` : str (default: "console") - Language identifier for examples code blocks. - -``argparse_examples_code_classes`` : list[str] (default: ["highlight-console"]) - CSS classes added to examples code blocks. - -``argparse_usage_code_language`` : str (default: "cli-usage") - Language identifier for usage blocks. - -**Behavior:** - -``argparse_reorder_usage_before_examples`` : bool (default: True) - Whether to reorder nodes so usage appears before examples. - -Additional Features -------------------- -- Removes ANSI escape codes (useful when FORCE_COLOR is set) -- Applies syntax highlighting to usage blocks -- Reorders sections so usage appears before examples in the output -- Extracts sections from argparse_program containers for TOC visibility - -Project-Specific Setup ----------------------- -Projects using this extension should register their own lexers and CSS in -their conf.py setup() function. For example:: - - def setup(app): - from my_lexer import MyLexer - app.add_lexer("my-output", MyLexer) - app.add_css_file("css/my-highlight.css") -""" - -from __future__ import annotations - -import dataclasses -import typing as t - -from docutils import nodes -from sphinx_argparse_neo.directive import ArgparseDirective -from sphinx_argparse_neo.utils import strip_ansi - -if t.TYPE_CHECKING: - import sphinx.config - from sphinx.application import Sphinx - - -@dataclasses.dataclass -class ExemplarConfig: - """Configuration for argparse_exemplar transformation. - - This dataclass provides all configurable options for the argparse_exemplar - extension. Functions accept an optional config parameter with a factory - default, allowing them to work standalone with defaults or accept custom - config for full control. - - Attributes - ---------- - examples_term_suffix : str - Term must end with this string (case-insensitive) to be treated as an - examples header. Default: "examples". - examples_base_term : str - Exact match (case-insensitive, after stripping ":") for the base - examples section. Default: "examples". - examples_section_title : str - Title used for the base examples section. Default: "Examples". - usage_pattern : str - Text must start with this string (case-insensitive, after stripping - whitespace) to be treated as a usage block. Default: "usage:". - command_prefix : str - Prefix added to each command line in examples code blocks. - Default: "$ ". - code_language : str - Language identifier for examples code blocks. Default: "console". - code_classes : tuple[str, ...] - CSS classes added to examples code blocks. - Default: ("highlight-console",). - usage_code_language : str - Language identifier for usage blocks. Default: "cli-usage". - reorder_usage_before_examples : bool - Whether to reorder nodes so usage appears before examples. - Default: True. - - Examples - -------- - Using default configuration: - - >>> config = ExemplarConfig() - >>> config.examples_term_suffix - 'examples' - >>> config.command_prefix - '$ ' - - Custom configuration: - - >>> config = ExemplarConfig( - ... command_prefix="> ", - ... code_language="bash", - ... ) - >>> config.command_prefix - '> ' - >>> config.code_language - 'bash' - """ - - # Term detection - examples_term_suffix: str = "examples" - examples_base_term: str = "examples" - examples_section_title: str = "Examples" - - # Usage detection - usage_pattern: str = "usage:" - - # Code block formatting - command_prefix: str = "$ " - code_language: str = "console" - code_classes: tuple[str, ...] = ("highlight-console",) - usage_code_language: str = "cli-usage" - - # Behavior - reorder_usage_before_examples: bool = True - - @classmethod - def from_sphinx_config(cls, config: sphinx.config.Config) -> ExemplarConfig: - """Create ExemplarConfig from Sphinx configuration. - - Parameters - ---------- - config : sphinx.config.Config - The Sphinx configuration object. - - Returns - ------- - ExemplarConfig - Configuration populated from Sphinx config values. - - Examples - -------- - This is typically called from a directive's run() method: - - >>> # In CleanArgParseDirective.run(): - >>> # config = ExemplarConfig.from_sphinx_config(self.env.config) - """ - # Get code_classes as tuple (Sphinx stores lists) - code_classes_raw = getattr( - config, "argparse_examples_code_classes", ("highlight-console",) - ) - code_classes = ( - tuple(code_classes_raw) - if isinstance(code_classes_raw, list) - else code_classes_raw - ) - - return cls( - examples_term_suffix=getattr( - config, "argparse_examples_term_suffix", "examples" - ), - examples_base_term=getattr( - config, "argparse_examples_base_term", "examples" - ), - examples_section_title=getattr( - config, "argparse_examples_section_title", "Examples" - ), - usage_pattern=getattr(config, "argparse_usage_pattern", "usage:"), - command_prefix=getattr(config, "argparse_examples_command_prefix", "$ "), - code_language=getattr(config, "argparse_examples_code_language", "console"), - code_classes=code_classes, - usage_code_language=getattr( - config, "argparse_usage_code_language", "cli-usage" - ), - reorder_usage_before_examples=getattr( - config, "argparse_reorder_usage_before_examples", True - ), - ) - - -# Re-export for backwards compatibility and public API -__all__ = [ - "CleanArgParseDirective", - "ExemplarConfig", - "is_base_examples_term", - "is_examples_term", - "make_section_id", - "make_section_title", - "process_node", - "strip_ansi", - "transform_definition_list", -] - - -def is_examples_term(term_text: str, *, config: ExemplarConfig | None = None) -> bool: - """Check if a definition term is an examples header. - - Parameters - ---------- - term_text : str - The text content of a definition term. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - bool - True if this is an examples header. - - Examples - -------- - >>> is_examples_term("examples:") - True - >>> is_examples_term("Machine-readable output examples:") - True - >>> is_examples_term("Usage:") - False - - With custom configuration: - - >>> custom_config = ExemplarConfig(examples_term_suffix="demos") - >>> is_examples_term("demos:", config=custom_config) - True - >>> is_examples_term("examples:", config=custom_config) - False - """ - config = config or ExemplarConfig() - return term_text.lower().rstrip(":").endswith(config.examples_term_suffix) - - -def is_base_examples_term( - term_text: str, *, config: ExemplarConfig | None = None -) -> bool: - """Check if a definition term is a base "examples:" header (no prefix). - - Parameters - ---------- - term_text : str - The text content of a definition term. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - bool - True if this is just "examples:" with no category prefix. - - Examples - -------- - >>> is_base_examples_term("examples:") - True - >>> is_base_examples_term("Examples") - True - >>> is_base_examples_term("Field-scoped examples:") - False - - With custom configuration: - - >>> custom_config = ExemplarConfig(examples_base_term="demos") - >>> is_base_examples_term("demos:", config=custom_config) - True - >>> is_base_examples_term("examples:", config=custom_config) - False - """ - config = config or ExemplarConfig() - return term_text.lower().rstrip(":").strip() == config.examples_base_term - - -def make_section_id( - term_text: str, - counter: int = 0, - *, - is_subsection: bool = False, - page_prefix: str = "", - config: ExemplarConfig | None = None, -) -> 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. - page_prefix : str - Optional prefix from the page name (e.g., "sync", "add") to ensure - uniqueness across different documentation pages. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - str - A normalized section ID. - - Examples - -------- - >>> make_section_id("examples:") - 'examples' - >>> make_section_id("examples:", page_prefix="sync") - 'sync-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' - - With custom configuration: - - >>> custom_config = ExemplarConfig(examples_term_suffix="demos") - >>> make_section_id("demos:", config=custom_config) - 'demos' - >>> make_section_id("Machine-readable output demos:", config=custom_config) - 'machine-readable-output-demos' - """ - config = config or ExemplarConfig() - term_suffix = config.examples_term_suffix - - # Extract prefix before the term suffix (e.g., "Machine-readable output") - lower_text = term_text.lower().rstrip(":") - if term_suffix in lower_text: - prefix = lower_text.rsplit(term_suffix, 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}-{term_suffix}" - else: - # Plain "examples" - add page prefix if provided for uniqueness - section_id = f"{page_prefix}-{term_suffix}" if page_prefix else term_suffix - else: - section_id = term_suffix - - # 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, - config: ExemplarConfig | None = None, -) -> str: - """Generate a section title from an examples term. - - Parameters - ---------- - term_text : str - The examples term text (e.g., "Machine-readable output: examples:") - is_subsection : bool - If True, omit "Examples" suffix for cleaner nested titles. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - str - A proper title (e.g., "Machine-readable Output Examples" or just - "Machine-Readable Output" if is_subsection=True). - - Examples - -------- - >>> make_section_title("examples:") - 'Examples' - >>> make_section_title("Machine-readable output examples:") - 'Machine-Readable Output Examples' - >>> make_section_title("Field-scoped examples:", is_subsection=True) - 'Field-Scoped' - - With custom configuration: - - >>> custom_config = ExemplarConfig( - ... examples_base_term="demos", - ... examples_term_suffix="demos", - ... examples_section_title="Demos", - ... ) - >>> make_section_title("demos:", config=custom_config) - 'Demos' - >>> make_section_title("Machine-readable output demos:", config=custom_config) - 'Machine-Readable Output Demos' - """ - config = config or ExemplarConfig() - base_term = config.examples_base_term - term_suffix = config.examples_term_suffix - section_title = config.examples_section_title - - # Remove trailing colon and normalize - text = term_text.rstrip(":").strip() - # Handle base term case (e.g., "examples:") - if text.lower() == base_term: - return section_title - - # Extract the prefix (category name) before the term suffix - lower = text.lower() - colon_suffix = f": {term_suffix}" - space_suffix = f" {term_suffix}" - if lower.endswith(colon_suffix): - prefix = text[: -len(colon_suffix)] - elif lower.endswith(space_suffix): - prefix = text[: -len(space_suffix)] - else: - prefix = text - - # Title case the prefix - titled_prefix = prefix.title() - - # For subsections, just use the prefix (cleaner nested titles) - if is_subsection: - return titled_prefix - - # For top-level sections, append the section title - return f"{titled_prefix} {section_title}" - - -def _create_example_section( - term_text: str, - def_node: nodes.definition, - *, - is_subsection: bool = False, - page_prefix: str = "", - config: ExemplarConfig | None = None, -) -> nodes.section: - """Create a section node for an examples item. - - Parameters - ---------- - term_text : str - The examples term text. - def_node : nodes.definition - The definition node containing example commands. - is_subsection : bool - If True, create a subsection with simpler title/id. - page_prefix : str - Optional prefix from the page name for unique section IDs. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - nodes.section - A section node with title and code blocks. - - Examples - -------- - Create a section from a definition node containing example commands: - - >>> from docutils import nodes - >>> def_node = nodes.definition() - >>> def_node += nodes.paragraph(text="myapp sync") - >>> section = _create_example_section("examples:", def_node) - >>> section["ids"] - ['examples'] - >>> section[0].astext() - 'Examples' - - With a page prefix for uniqueness across documentation pages: - - >>> section = _create_example_section("examples:", def_node, page_prefix="sync") - >>> section["ids"] - ['sync-examples'] - - Category-prefixed examples create descriptive section IDs: - - >>> section = _create_example_section("Machine-readable output examples:", def_node) - >>> section["ids"] - ['machine-readable-output-examples'] - >>> section[0].astext() - 'Machine-Readable Output Examples' - """ - config = config or ExemplarConfig() - section_id = make_section_id( - term_text, is_subsection=is_subsection, page_prefix=page_prefix, config=config - ) - section_title = make_section_title( - term_text, is_subsection=is_subsection, config=config - ) - - section = nodes.section() - section["ids"] = [section_id] - section["names"] = [nodes.fully_normalize_name(section_title)] - - title = nodes.title(text=section_title) - section += title - - # Extract commands from definition and create separate code blocks - def_text = strip_ansi(def_node.astext()) - for line in def_text.split("\n"): - line = line.strip() - if line: - code_block = nodes.literal_block( - text=f"{config.command_prefix}{line}", - classes=list(config.code_classes), - ) - code_block["language"] = config.code_language - section += code_block - - return section - - -def transform_definition_list( - dl_node: nodes.definition_list, - *, - page_prefix: str = "", - config: ExemplarConfig | None = None, -) -> list[nodes.Node]: - """Transform a definition list, converting examples items to code blocks. - - If there's a base "examples:" item followed by category-specific examples - (e.g., "Field-scoped: examples:"), the categories are nested under the - parent Examples section for cleaner ToC structure. - - Parameters - ---------- - dl_node : nodes.definition_list - A definition list node. - page_prefix : str - Optional prefix from the page name for unique section IDs. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - list[nodes.Node] - Transformed nodes - code blocks for examples, original for others. - - Note - ---- - **Intentional reordering behavior:** This function always emits non-example - items (preamble text, descriptions, etc.) before example sections, regardless - of their original position in the definition list. This "flush first" approach - groups conceptually related content: introductory material appears before - examples, even if the source document interleaves them. This produces cleaner - documentation structure where descriptions introduce their examples. - - If you need to preserve the original interleaved order, you would need to - modify this function to track item positions during the first pass. - """ - config = config or ExemplarConfig() - - # First pass: collect examples and non-examples items separately - example_items: list[tuple[str, nodes.definition]] = [] # (term_text, def_node) - non_example_items: list[nodes.Node] = [] - base_examples_index: int | None = None - - for item in dl_node.children: - if not isinstance(item, nodes.definition_list_item): - continue - - # Get the term and definition - term_node = None - def_node = None - for child in item.children: - if isinstance(child, nodes.term): - term_node = child - elif isinstance(child, nodes.definition): - def_node = child - - if term_node is None or def_node is None: - non_example_items.append(item) - continue - - term_text = strip_ansi(term_node.astext()) - - if is_examples_term(term_text, config=config): - if is_base_examples_term(term_text, config=config): - base_examples_index = len(example_items) - example_items.append((term_text, def_node)) - else: - non_example_items.append(item) - - # Build result nodes - result_nodes: list[nodes.Node] = [] - - # Emit non-example items first (see docstring Note on reordering behavior) - if non_example_items: - new_dl = nodes.definition_list() - new_dl.extend(non_example_items) - result_nodes.append(new_dl) - - # Determine nesting strategy - # Nest if: there's a base "examples:" AND at least one other example category - should_nest = base_examples_index is not None and len(example_items) > 1 - - if should_nest and base_examples_index is not None: - # Create parent "Examples" section - base_term, base_def = example_items[base_examples_index] - parent_section = _create_example_section( - base_term, - base_def, - is_subsection=False, - page_prefix=page_prefix, - config=config, - ) - - # Add other examples as nested subsections - for i, (term_text, def_node) in enumerate(example_items): - if i == base_examples_index: - continue # Skip the base (already used as parent) - subsection = _create_example_section( - term_text, - def_node, - is_subsection=True, - page_prefix=page_prefix, - config=config, - ) - parent_section += subsection - - result_nodes.append(parent_section) - else: - # No nesting - create flat sections (backwards compatible) - for term_text, def_node in example_items: - section = _create_example_section( - term_text, - def_node, - is_subsection=False, - page_prefix=page_prefix, - config=config, - ) - result_nodes.append(section) - - return result_nodes - - -def process_node( - node: nodes.Node, - *, - page_prefix: str = "", - config: ExemplarConfig | None = None, -) -> nodes.Node | list[nodes.Node]: - """Process a node: strip ANSI codes and transform examples. - - Parameters - ---------- - node : nodes.Node - A docutils node to process. - page_prefix : str - Optional prefix from the page name for unique section IDs. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - nodes.Node | list[nodes.Node] - The processed node(s). - """ - config = config or ExemplarConfig() - - # Handle text nodes - strip ANSI - if isinstance(node, nodes.Text): - cleaned = strip_ansi(node.astext()) - if cleaned != node.astext(): - return nodes.Text(cleaned) - return node - - # Handle definition lists - transform examples - if isinstance(node, nodes.definition_list): - # Check if any items are examples - has_examples = False - for item in node.children: - if isinstance(item, nodes.definition_list_item): - for child in item.children: - if isinstance(child, nodes.term) and is_examples_term( - strip_ansi(child.astext()), config=config - ): - has_examples = True - break - if has_examples: - break - - if has_examples: - return transform_definition_list( - node, page_prefix=page_prefix, config=config - ) - - # Handle literal_block nodes - strip ANSI and apply usage highlighting - if isinstance(node, nodes.literal_block): - text = strip_ansi(node.astext()) - needs_update = text != node.astext() - - # Check if this is a usage block (starts with configured pattern) - is_usage = text.lstrip().lower().startswith(config.usage_pattern.lower()) - - if needs_update or is_usage: - new_block = nodes.literal_block(text=text) - # Preserve attributes - for attr in ("language", "classes"): - if attr in node: - new_block[attr] = node[attr] - # Apply configured language to usage blocks - if is_usage: - new_block["language"] = config.usage_code_language - return new_block - return node - - # Handle paragraph nodes - strip ANSI and lift sections out - if isinstance(node, nodes.paragraph): - # Process children and check if any become sections - processed_children: list[nodes.Node] = [] - changed = False - has_sections = False - - for child in node.children: - if isinstance(child, nodes.Text): - cleaned = strip_ansi(child.astext()) - if cleaned != child.astext(): - processed_children.append(nodes.Text(cleaned)) - changed = True - else: - processed_children.append(child) - else: - result = process_node(child, page_prefix=page_prefix, config=config) - if isinstance(result, list): - processed_children.extend(result) - changed = True - # Check if any results are sections - if any(isinstance(r, nodes.section) for r in result): - has_sections = True - elif result is not child: - processed_children.append(result) - changed = True - if isinstance(result, nodes.section): - has_sections = True - else: - processed_children.append(child) - - if not changed: - return node - - # If no sections, return a normal paragraph - if not has_sections: - new_para = nodes.paragraph() - new_para.extend(processed_children) - return new_para - - # Sections found - lift them out of the paragraph - # Return a list: [para_before, section1, section2, ..., para_after] - result_nodes: list[nodes.Node] = [] - current_para_children: list[nodes.Node] = [] - - for child in processed_children: - if isinstance(child, nodes.section): - # Flush current paragraph content - if current_para_children: - para = nodes.paragraph() - para.extend(current_para_children) - result_nodes.append(para) - current_para_children = [] - # Add section as a sibling - result_nodes.append(child) - else: - current_para_children.append(child) - - # Flush remaining paragraph content - if current_para_children: - para = nodes.paragraph() - para.extend(current_para_children) - result_nodes.append(para) - - return result_nodes - - # Recursively process children for other node types - if hasattr(node, "children"): - new_children: list[nodes.Node] = [] - children_changed = False - for child in node.children: - result = process_node(child, page_prefix=page_prefix, config=config) - if isinstance(result, list): - new_children.extend(result) - children_changed = True - elif result is not child: - new_children.append(result) - children_changed = True - else: - new_children.append(child) - if children_changed: - node[:] = new_children # type: ignore[index] - - return node - - -def _is_usage_block(node: nodes.Node, *, config: ExemplarConfig | None = None) -> bool: - """Check if a node is a usage literal block. - - Parameters - ---------- - node : nodes.Node - A docutils node to check. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - bool - True if this is a usage block (literal_block starting with usage pattern). - - Examples - -------- - >>> from docutils import nodes - >>> _is_usage_block(nodes.literal_block(text="usage: cmd [-h]")) - True - >>> _is_usage_block(nodes.literal_block(text="Usage: myapp sync")) - True - >>> _is_usage_block(nodes.literal_block(text=" usage: cmd")) - True - >>> _is_usage_block(nodes.literal_block(text="some other text")) - False - >>> _is_usage_block(nodes.paragraph(text="usage: cmd")) - False - >>> _is_usage_block(nodes.section()) - False - - With custom configuration: - - >>> custom_config = ExemplarConfig(usage_pattern="synopsis:") - >>> _is_usage_block(nodes.literal_block(text="synopsis: cmd"), config=custom_config) - True - >>> _is_usage_block(nodes.literal_block(text="usage: cmd"), config=custom_config) - False - """ - config = config or ExemplarConfig() - if not isinstance(node, nodes.literal_block): - return False - text = node.astext() - return text.lstrip().lower().startswith(config.usage_pattern.lower()) - - -def _is_usage_section(node: nodes.Node) -> bool: - """Check if a node is a usage section. - - Parameters - ---------- - node : nodes.Node - A docutils node to check. - - Returns - ------- - bool - True if this is a section with "usage" in its ID. - - Examples - -------- - >>> from docutils import nodes - >>> section = nodes.section() - >>> section["ids"] = ["usage"] - >>> _is_usage_section(section) - True - >>> section2 = nodes.section() - >>> section2["ids"] = ["sync-usage"] - >>> _is_usage_section(section2) - True - >>> section3 = nodes.section() - >>> section3["ids"] = ["options"] - >>> _is_usage_section(section3) - False - >>> _is_usage_section(nodes.paragraph()) - False - """ - if not isinstance(node, nodes.section): - return False - ids: list[str] = node.get("ids", []) - return any(id_str == "usage" or id_str.endswith("-usage") for id_str in ids) - - -def _is_examples_section( - node: nodes.Node, *, config: ExemplarConfig | None = None -) -> bool: - """Check if a node is an examples section. - - Parameters - ---------- - node : nodes.Node - A docutils node to check. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - bool - True if this is an examples section (section with term suffix in its ID). - - Examples - -------- - >>> from docutils import nodes - >>> section = nodes.section() - >>> section["ids"] = ["examples"] - >>> _is_examples_section(section) - True - >>> section2 = nodes.section() - >>> section2["ids"] = ["machine-readable-output-examples"] - >>> _is_examples_section(section2) - True - >>> section3 = nodes.section() - >>> section3["ids"] = ["positional-arguments"] - >>> _is_examples_section(section3) - False - >>> _is_examples_section(nodes.paragraph()) - False - >>> _is_examples_section(nodes.literal_block(text="examples")) - False - - With custom configuration: - - >>> custom_config = ExemplarConfig(examples_term_suffix="demos") - >>> section = nodes.section() - >>> section["ids"] = ["demos"] - >>> _is_examples_section(section, config=custom_config) - True - >>> section2 = nodes.section() - >>> section2["ids"] = ["examples"] - >>> _is_examples_section(section2, config=custom_config) - False - """ - config = config or ExemplarConfig() - if not isinstance(node, nodes.section): - return False - ids: list[str] = node.get("ids", []) - return any(config.examples_term_suffix in id_str.lower() for id_str in ids) - - -def _reorder_nodes( - processed: list[nodes.Node], *, config: ExemplarConfig | None = None -) -> list[nodes.Node]: - """Reorder nodes so usage sections/blocks appear before examples sections. - - This ensures the CLI usage synopsis appears above examples in the - documentation, making it easier to understand command syntax before - seeing example invocations. - - The function handles both: - - Usage as literal_block (legacy format from older renderer) - - Usage as section#usage (new format with TOC support) - - Parameters - ---------- - processed : list[nodes.Node] - List of processed docutils nodes. - config : ExemplarConfig | None - Optional configuration. If None, uses default ExemplarConfig(). - - Returns - ------- - list[nodes.Node] - Reordered nodes with usage before examples (if enabled). - - Examples - -------- - >>> from docutils import nodes - - Create test nodes: - - >>> desc = nodes.paragraph(text="Description") - >>> examples = nodes.section() - >>> examples["ids"] = ["examples"] - >>> usage = nodes.literal_block(text="usage: cmd [-h]") - >>> args = nodes.section() - >>> args["ids"] = ["arguments"] - - When usage appears after examples, it gets moved before: - - >>> result = _reorder_nodes([desc, examples, usage, args]) - >>> [type(n).__name__ for n in result] - ['paragraph', 'literal_block', 'section', 'section'] - - When no examples exist, order is unchanged: - - >>> result = _reorder_nodes([desc, usage, args]) - >>> [type(n).__name__ for n in result] - ['paragraph', 'literal_block', 'section'] - - When usage already before examples, order is preserved: - - >>> result = _reorder_nodes([desc, usage, examples, args]) - >>> [type(n).__name__ for n in result] - ['paragraph', 'literal_block', 'section', 'section'] - - Empty list returns empty: - - >>> _reorder_nodes([]) - [] - - Usage sections (with TOC heading) are also handled: - - >>> usage_section = nodes.section() - >>> usage_section["ids"] = ["usage"] - >>> result = _reorder_nodes([desc, examples, usage_section, args]) - >>> [n.get("ids", []) for n in result if isinstance(n, nodes.section)] - [['usage'], ['examples'], ['arguments']] - - Reordering can be disabled via config: - - >>> no_reorder_config = ExemplarConfig(reorder_usage_before_examples=False) - >>> result = _reorder_nodes([desc, examples, usage, args], config=no_reorder_config) - >>> [type(n).__name__ for n in result] - ['paragraph', 'section', 'literal_block', 'section'] - """ - config = config or ExemplarConfig() - - # If reordering is disabled, return as-is - if not config.reorder_usage_before_examples: - return processed - - # First pass: check if there are any examples sections - has_examples = any(_is_examples_section(node, config=config) for node in processed) - if not has_examples: - # No examples, preserve original order - return processed - - usage_nodes: list[nodes.Node] = [] - examples_sections: list[nodes.Node] = [] - other_before_examples: list[nodes.Node] = [] - other_after_examples: list[nodes.Node] = [] - - seen_examples = False - for node in processed: - # Check for both usage block (literal_block) and usage section - if _is_usage_block(node, config=config) or _is_usage_section(node): - usage_nodes.append(node) - elif _is_examples_section(node, config=config): - examples_sections.append(node) - seen_examples = True - elif not seen_examples: - other_before_examples.append(node) - else: - other_after_examples.append(node) - - # Order: before_examples → usage → examples → after_examples - return ( - other_before_examples + usage_nodes + examples_sections + other_after_examples - ) - - -def _extract_sections_from_container( - container: nodes.Node, -) -> tuple[nodes.Node, list[nodes.section]]: - """Extract section nodes from a container, returning modified container. - - This function finds any section nodes that are children of the container - (typically argparse_program), removes them from the container, and returns - them separately so they can be made siblings. - - This is needed because Sphinx's TocTreeCollector only discovers sections - that are direct children of the document or properly nested in the section - hierarchy - sections inside arbitrary div containers are invisible to TOC. - - Parameters - ---------- - container : nodes.Node - A container node (typically argparse_program) that may contain sections. - - Returns - ------- - tuple[nodes.Node, list[nodes.section]] - A tuple of (modified_container, extracted_sections). - - Examples - -------- - >>> from docutils import nodes - >>> from sphinx_argparse_neo.nodes import argparse_program - >>> container = argparse_program() - >>> para = nodes.paragraph(text="Description") - >>> examples = nodes.section() - >>> examples["ids"] = ["examples"] - >>> container += para - >>> container += examples - >>> modified, extracted = _extract_sections_from_container(container) - >>> len(modified.children) - 1 - >>> len(extracted) - 1 - >>> extracted[0]["ids"] - ['examples'] - """ - if not hasattr(container, "children"): - return container, [] - - extracted_sections: list[nodes.section] = [] - remaining_children: list[nodes.Node] = [] - - for child in container.children: - if isinstance(child, nodes.section): - extracted_sections.append(child) - else: - remaining_children.append(child) - - # Update container with remaining children only - container[:] = remaining_children # type: ignore[index] - - return container, extracted_sections - - -class CleanArgParseDirective(ArgparseDirective): # type: ignore[misc] - """ArgParse directive that strips ANSI codes and formats examples.""" - - def run(self) -> list[nodes.Node]: - """Run the directive, clean output, format examples, and reorder. - - The processing pipeline: - 1. Run base directive to get initial nodes - 2. Load configuration from Sphinx config - 3. Process each node (strip ANSI, transform examples definition lists) - 4. Extract sections from inside argparse_program containers - 5. Reorder so usage appears before examples (if enabled) - """ - result = super().run() - - # Load configuration from Sphinx - config = ExemplarConfig.from_sphinx_config(self.env.config) - - # Extract page name for unique section IDs across different CLI pages - page_prefix = "" - if hasattr(self.state, "document"): - settings = self.state.document.settings - if hasattr(settings, "env") and hasattr(settings.env, "docname"): - # docname is like "cli/sync" - extract "sync" - docname = settings.env.docname - page_prefix = docname.split("/")[-1] - - processed: list[nodes.Node] = [] - for node in result: - processed_node = process_node(node, page_prefix=page_prefix, config=config) - if isinstance(processed_node, list): - processed.extend(processed_node) - else: - processed.append(processed_node) - - # Extract sections from inside argparse_program containers - # This is needed because sections inside divs are invisible to Sphinx TOC - flattened: list[nodes.Node] = [] - for node in processed: - # Check if this is an argparse_program (or similar container) - # that might have sections inside - node_class_name = type(node).__name__ - if node_class_name == "argparse_program": - modified, extracted = _extract_sections_from_container(node) - flattened.append(modified) - flattened.extend(extracted) - else: - flattened.append(node) - - # Reorder: usage sections/blocks before examples sections - return _reorder_nodes(flattened, config=config) - - -def setup(app: Sphinx) -> dict[str, t.Any]: - """Register the clean argparse directive, lexers, and CLI roles. - - Configuration Options - --------------------- - The following configuration options can be set in conf.py: - - ``argparse_examples_term_suffix`` : str (default: "examples") - Term must end with this string to be treated as examples header. - - ``argparse_examples_base_term`` : str (default: "examples") - Exact match for the base examples section. - - ``argparse_examples_section_title`` : str (default: "Examples") - Title used for the base examples section. - - ``argparse_usage_pattern`` : str (default: "usage:") - Text must start with this to be treated as a usage block. - - ``argparse_examples_command_prefix`` : str (default: "$ ") - Prefix added to each command line in examples code blocks. - - ``argparse_examples_code_language`` : str (default: "console") - Language identifier for examples code blocks. - - ``argparse_examples_code_classes`` : list[str] (default: ["highlight-console"]) - CSS classes added to examples code blocks. - - ``argparse_usage_code_language`` : str (default: "cli-usage") - Language identifier for usage blocks. - - ``argparse_reorder_usage_before_examples`` : bool (default: True) - Whether to reorder nodes so usage appears before examples. - - Parameters - ---------- - app : Sphinx - The Sphinx application object. - - Returns - ------- - dict - Extension metadata. - """ - # Load the base sphinx_argparse_neo extension first - app.setup_extension("sphinx_argparse_neo") - - # Register configuration options - app.add_config_value("argparse_examples_term_suffix", "examples", "html") - app.add_config_value("argparse_examples_base_term", "examples", "html") - app.add_config_value("argparse_examples_section_title", "Examples", "html") - app.add_config_value("argparse_usage_pattern", "usage:", "html") - app.add_config_value("argparse_examples_command_prefix", "$ ", "html") - app.add_config_value("argparse_examples_code_language", "console", "html") - app.add_config_value( - "argparse_examples_code_classes", ["highlight-console"], "html" - ) - app.add_config_value("argparse_usage_code_language", "cli-usage", "html") - app.add_config_value("argparse_reorder_usage_before_examples", True, "html") - - # Override the argparse directive with our enhanced version - app.add_directive("argparse", CleanArgParseDirective, override=True) - - # Register CLI usage lexer for usage block highlighting - from cli_usage_lexer import CLIUsageLexer - - app.add_lexer("cli-usage", CLIUsageLexer) - - # Register argparse lexers for help output highlighting - from argparse_lexer import ( - ArgparseHelpLexer, - ArgparseLexer, - ArgparseUsageLexer, - ) - - app.add_lexer("argparse", ArgparseLexer) - app.add_lexer("argparse-usage", ArgparseUsageLexer) - app.add_lexer("argparse-help", ArgparseHelpLexer) - - # Register CLI inline roles for documentation - from argparse_roles import register_roles - - register_roles() - - return {"version": "4.0", "parallel_read_safe": True} diff --git a/docs/_ext/argparse_lexer.py b/docs/_ext/argparse_lexer.py deleted file mode 100644 index 14aed55649..0000000000 --- a/docs/_ext/argparse_lexer.py +++ /dev/null @@ -1,429 +0,0 @@ -"""Pygments lexers for argparse help output. - -This module provides custom Pygments lexers for highlighting argparse-generated -command-line help text, including usage lines, section headers, and full help output. - -Three lexer classes are provided: -- ArgparseUsageLexer: For usage lines only -- ArgparseHelpLexer: For full -h output (delegates usage to ArgparseUsageLexer) -- ArgparseLexer: Smart auto-detecting wrapper -""" - -from __future__ import annotations - -from pygments.lexer import RegexLexer, bygroups, include -from pygments.token import Generic, Name, Operator, Punctuation, Text, Whitespace - - -class ArgparseUsageLexer(RegexLexer): - """Lexer for argparse usage lines only. - - Handles patterns like: - - usage: PROG [-h] [--foo FOO] bar {a,b,c} - - Mutually exclusive: [-a | -b], (--foo | --bar) - - Choices: {json,yaml,table} - - Variadic: FILE ..., [FILE ...], [--foo [FOO]] - - Examples - -------- - >>> from pygments.token import Token - >>> lexer = ArgparseUsageLexer() - >>> tokens = list(lexer.get_tokens("usage: cmd [-h]")) - >>> tokens[0] - (Token.Generic.Heading, 'usage:') - >>> tokens[2] - (Token.Name.Label, 'cmd') - """ - - name = "Argparse Usage" - aliases = ["argparse-usage"] # noqa: RUF012 - filenames: list[str] = [] # noqa: RUF012 - mimetypes = ["text/x-argparse-usage"] # noqa: RUF012 - - tokens = { # noqa: RUF012 - "root": [ - # "usage:" at start of line - then look for program name - ( - r"^(usage:)(\s+)", - bygroups(Generic.Heading, Whitespace), # type: ignore[no-untyped-call] - "after_usage", - ), - # Continuation lines (leading whitespace for wrapped usage) - (r"^(\s+)(?=\S)", Whitespace), - include("inline"), - ], - "after_usage": [ - # Whitespace - (r"\s+", Whitespace), - # Program name (first lowercase word after usage:) - (r"\b[a-z][-a-z0-9_]*\b", Name.Label, "usage_body"), - # Fallback to inline if something unexpected - include("inline"), - ], - "usage_body": [ - # Whitespace - (r"\s+", Whitespace), - # Ellipsis for variadic args (before other patterns) - (r"\.\.\.", Punctuation), - # 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), # type: ignore[no-untyped-call] - ), - # 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), # type: ignore[no-untyped-call] - ), - # Short options standalone - (r"-[a-zA-Z0-9]", Name.Attribute), - # Opening brace - enter choices state - (r"\{", Punctuation, "choices"), - # Opening bracket - enter optional state - (r"\[", Punctuation, "optional"), - # Closing bracket (fallback for unmatched) - (r"\]", Punctuation), - # Opening paren - enter required mutex state - (r"\(", Punctuation, "required"), - # Closing paren (fallback for unmatched) - (r"\)", Punctuation), - # Choice separator (pipe) for mutex groups - (r"\|", Operator), - # UPPERCASE meta-variables (COMMAND, FILE, PATH) - (r"\b[A-Z][A-Z0-9_]*\b", Name.Variable), - # Subcommand/positional names (Name.Function for distinct styling) - (r"\b[a-z][-a-z0-9_]*\b", Name.Function), - # Catch-all for any other text - (r"[^\s\[\]|(){},]+", Text), - ], - "inline": [ - # Whitespace - (r"\s+", Whitespace), - # Ellipsis for variadic args (before other patterns) - (r"\.\.\.", Punctuation), - # 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), # type: ignore[no-untyped-call] - ), - # 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), # type: ignore[no-untyped-call] - ), - # Short options standalone - (r"-[a-zA-Z0-9]", Name.Attribute), - # Opening brace - enter choices state - (r"\{", Punctuation, "choices"), - # Opening bracket - enter optional state - (r"\[", Punctuation, "optional"), - # Closing bracket (fallback for unmatched) - (r"\]", Punctuation), - # Opening paren - enter required mutex state - (r"\(", Punctuation, "required"), - # Closing paren (fallback for unmatched) - (r"\)", Punctuation), - # Choice separator (pipe) for mutex groups - (r"\|", Operator), - # UPPERCASE meta-variables (COMMAND, FILE, PATH) - (r"\b[A-Z][A-Z0-9_]*\b", Name.Variable), - # 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 usage_body rules (subcommands are green) - include("usage_body"), - ], - "required": [ - # Nested required paren - (r"\(", Punctuation, "#push"), - # End required - (r"\)", Punctuation, "#pop"), - # Contents use usage_body rules (subcommands are green) - include("usage_body"), - ], - "choices": [ - # Choice values (comma-separated inside braces) - (r"[a-zA-Z0-9][-a-zA-Z0-9_]*", Name.Constant), - # Comma separator - (r",", Punctuation), - # End choices - (r"\}", Punctuation, "#pop"), - # Whitespace - (r"\s+", Whitespace), - ], - } - - -class ArgparseHelpLexer(RegexLexer): - """Lexer for full argparse -h help output. - - Handles: - - Usage lines (delegates to ArgparseUsageLexer patterns) - - Section headers (positional arguments:, options:, etc.) - - Option entries with help text - - Indented descriptions - - Examples - -------- - >>> from pygments.token import Token - >>> lexer = ArgparseHelpLexer() - >>> tokens = list(lexer.get_tokens("positional arguments:")) - >>> any(t[0] == Token.Generic.Subheading for t in tokens) - True - >>> tokens = list(lexer.get_tokens(" -h, --help show help")) - >>> any(t[0] == Token.Name.Attribute for t in tokens) - True - """ - - name = "Argparse Help" - aliases = ["argparse-help"] # noqa: RUF012 - filenames: list[str] = [] # noqa: RUF012 - mimetypes = ["text/x-argparse-help"] # noqa: RUF012 - - tokens = { # noqa: RUF012 - "root": [ - # "usage:" line - switch to after_usage to find program name - ( - r"^(usage:)(\s+)", - bygroups(Generic.Heading, Whitespace), # type: ignore[no-untyped-call] - "after_usage", - ), - # Section headers (e.g., "positional arguments:", "options:") - (r"^([a-zA-Z][-a-zA-Z0-9_ ]*:)\s*$", Generic.Subheading), - # Option entry lines (indented with spaces/tabs, not just newlines) - (r"^([ \t]+)", Whitespace, "option_line"), - # Continuation of usage (leading spaces/tabs followed by content) - (r"^([ \t]+)(?=\S)", Whitespace), - # Anything else (must match at least one char to avoid infinite loop) - (r".+\n?", Text), - # Standalone newlines - (r"\n", Whitespace), - ], - "after_usage": [ - # Whitespace - (r"\s+", Whitespace), - # Program name (first lowercase word after usage:) - (r"\b[a-z][-a-z0-9_]*\b", Name.Label, "usage"), - # Fallback to usage if something unexpected - include("usage_inline"), - ], - "usage": [ - # End of usage on blank line or section header - (r"\n(?=[a-zA-Z][-a-zA-Z0-9_ ]*:\s*$)", Text, "#pop:2"), - (r"\n(?=\n)", Text, "#pop:2"), - # Usage content - use usage_inline rules (subcommands are green) - include("usage_inline"), - # Line continuation - (r"\n", Text), - ], - "usage_inline": [ - # Whitespace - (r"\s+", Whitespace), - # Ellipsis for variadic args - (r"\.\.\.", Punctuation), - # Long options with = 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), # type: ignore[no-untyped-call] - ), - # Long options standalone - (r"--[a-zA-Z0-9][-a-zA-Z0-9]*", Name.Tag), - # Short options with value - ( - r"(-[a-zA-Z0-9])(\s+)([A-Z][A-Z0-9_]*|[a-z][-a-z0-9_]*)", - bygroups(Name.Attribute, Whitespace, Name.Variable), # type: ignore[no-untyped-call] - ), - # Short options standalone - (r"-[a-zA-Z0-9]", Name.Attribute), - # Choices in braces - (r"\{", Punctuation, "choices"), - # Optional brackets - (r"\[", Punctuation, "optional"), - (r"\]", Punctuation), - # Required parens (mutex) - (r"\(", Punctuation, "required"), - (r"\)", Punctuation), - # Pipe for mutex - (r"\|", Operator), - # UPPERCASE metavars - (r"\b[A-Z][A-Z0-9_]*\b", Name.Variable), - # Subcommand/positional names (Name.Function for distinct styling) - (r"\b[a-z][-a-z0-9_]*\b", Name.Function), - # Other text - (r"[^\s\[\]|(){},\n]+", Text), - ], - "option_line": [ - # Short option with comma (e.g., "-h, --help") - ( - r"(-[a-zA-Z0-9])(,)(\s*)(--[a-zA-Z0-9][-a-zA-Z0-9]*)", - bygroups(Name.Attribute, Punctuation, Whitespace, Name.Tag), # type: ignore[no-untyped-call] - ), - # Long options with = 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), # type: ignore[no-untyped-call] - ), - # Long options with space-separated metavar - ( - r"(--[a-zA-Z0-9][-a-zA-Z0-9]*)(\s+)([A-Z][A-Z0-9_]+)", - bygroups(Name.Tag, Whitespace, Name.Variable), # type: ignore[no-untyped-call] - ), - # Long options standalone - (r"--[a-zA-Z0-9][-a-zA-Z0-9]*", Name.Tag), - # Short options with metavar - ( - r"(-[a-zA-Z0-9])(\s+)([A-Z][A-Z0-9_]+)", - bygroups(Name.Attribute, Whitespace, Name.Variable), # type: ignore[no-untyped-call] - ), - # Short options standalone - (r"-[a-zA-Z0-9]", Name.Attribute), - # Choices in braces - (r"\{", Punctuation, "option_choices"), - # Help text (everything after double space or large gap) - (r"([ \t]{2,})(.+)$", bygroups(Whitespace, Text)), # type: ignore[no-untyped-call] - # End of line - MUST come before \s+ to properly pop on newlines - (r"\n", Text, "#pop"), - # Other whitespace (spaces/tabs only, not newlines) - (r"[ \t]+", Whitespace), - # UPPERCASE metavars - (r"\b[A-Z][A-Z0-9_]*\b", Name.Variable), - # Anything else on the line - (r"[^\s\n]+", Text), - ], - "optional": [ - (r"\[", Punctuation, "#push"), - (r"\]", Punctuation, "#pop"), - include("usage_inline"), - ], - "required": [ - (r"\(", Punctuation, "#push"), - (r"\)", Punctuation, "#pop"), - include("usage_inline"), - ], - "choices": [ - (r"[a-zA-Z0-9][-a-zA-Z0-9_]*", Name.Constant), - (r",", Punctuation), - (r"\}", Punctuation, "#pop"), - (r"\s+", Whitespace), - ], - "option_choices": [ - (r"[a-zA-Z0-9][-a-zA-Z0-9_]*", Name.Constant), - (r",", Punctuation), - (r"\}", Punctuation, "#pop"), - (r"\s+", Whitespace), - ], - } - - -class ArgparseLexer(ArgparseHelpLexer): - """Smart auto-detecting lexer for argparse output. - - Inherits from ArgparseHelpLexer to properly handle Pygments' metaclass - token processing. Using inheritance (not token dict copying) avoids - shared mutable state that causes memory corruption. - - This is the recommended lexer for general argparse highlighting. - - Examples - -------- - >>> from pygments.token import Token - >>> lexer = ArgparseLexer() - - Usage line detection: - - >>> tokens = list(lexer.get_tokens("usage: cmd [-h]")) - >>> tokens[0] - (Token.Generic.Heading, 'usage:') - - Section header detection (Pygments appends newline to input): - - >>> tokens = list(lexer.get_tokens("positional arguments:")) - >>> any(t[0] == Token.Generic.Subheading for t in tokens) - True - - Option highlighting in option line context: - - >>> tokens = list(lexer.get_tokens(" -h, --help show help")) - >>> any(t[0] == Token.Name.Attribute for t in tokens) - True - """ - - name = "Argparse" - aliases = ["argparse"] # noqa: RUF012 - filenames: list[str] = [] # noqa: RUF012 - mimetypes = ["text/x-argparse"] # noqa: RUF012 - - # Tokens inherited from ArgparseHelpLexer - do NOT redefine or copy - - -def tokenize_argparse(text: str) -> list[tuple[str, str]]: - """Tokenize argparse text and return list of (token_type, value) tuples. - - Parameters - ---------- - text : str - Argparse help or usage text to tokenize. - - Returns - ------- - list[tuple[str, str]] - List of (token_type_name, text_value) tuples. - - Examples - -------- - >>> result = tokenize_argparse("usage: cmd [-h]") - >>> result[0] - ('Token.Generic.Heading', 'usage:') - >>> result[2] - ('Token.Name.Label', 'cmd') - - >>> result = tokenize_argparse("positional arguments:") - >>> any('Token.Generic.Subheading' in t[0] for t in result) - True - """ - lexer = ArgparseLexer() - return [ - (str(tok_type), tok_value) for tok_type, tok_value in lexer.get_tokens(text) - ] - - -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') - """ - lexer = ArgparseUsageLexer() - return [ - (str(tok_type), tok_value) for tok_type, tok_value in lexer.get_tokens(text) - ] diff --git a/docs/_ext/argparse_roles.py b/docs/_ext/argparse_roles.py deleted file mode 100644 index 86e5459a28..0000000000 --- a/docs/_ext/argparse_roles.py +++ /dev/null @@ -1,370 +0,0 @@ -"""Docutils inline roles for CLI/argparse highlighting. - -This module provides custom docutils roles for inline highlighting of CLI -elements in reStructuredText and MyST documentation. - -Available roles: -- :cli-option: - CLI options (--verbose, -h) -- :cli-metavar: - Metavar placeholders (FILE, PATH) -- :cli-command: - Command names (sync, add) -- :cli-default: - Default values (None, "default") -- :cli-choice: - Choice values (json, yaml) -""" - -from __future__ import annotations - -import typing as t - -from docutils import nodes -from docutils.parsers.rst import roles - -if t.TYPE_CHECKING: - from docutils.parsers.rst.states import Inliner - - -def normalize_options(options: dict[str, t.Any] | None) -> dict[str, t.Any]: - """Normalize role options, converting None to empty dict. - - Parameters - ---------- - options : dict | None - Options passed to the role. - - Returns - ------- - dict - Normalized options dict (never None). - - Examples - -------- - >>> normalize_options(None) - {} - >>> normalize_options({"class": "custom"}) - {'class': 'custom'} - """ - return options if options is not None else {} - - -def cli_option_role( - name: str, - rawtext: str, - text: str, - lineno: int, - inliner: Inliner | None, - options: dict[str, t.Any] | None = None, - content: list[str] | None = None, -) -> tuple[list[nodes.Node], list[nodes.system_message]]: - """Role for CLI options like --foo or -h. - - Generates a literal node with appropriate CSS classes for styling. - Long options (--foo) get 'cli-option-long', short options (-h) get - 'cli-option-short'. - - Parameters - ---------- - name : str - Local name of the role used in document. - rawtext : str - Full interpreted text including role markup. - text : str - Content between backticks. - lineno : int - Line number. - inliner : Inliner | None - Object that called the role (has .reporter, .document). - options : dict | None - Options from role directive. - content : list | None - Content from role directive. - - Returns - ------- - tuple[list[nodes.Node], list[nodes.system_message]] - Nodes to insert and any messages. - - Examples - -------- - >>> node_list, messages = cli_option_role( - ... "cli-option", ":cli-option:`--verbose`", "--verbose", - ... 1, None - ... ) - >>> node_list[0]["classes"] - ['cli-option', 'cli-option-long'] - - >>> node_list, messages = cli_option_role( - ... "cli-option", ":cli-option:`-h`", "-h", - ... 1, None - ... ) - >>> node_list[0]["classes"] - ['cli-option', 'cli-option-short'] - - >>> node_list, messages = cli_option_role( - ... "cli-option", ":cli-option:`--no-color`", "--no-color", - ... 1, None - ... ) - >>> node_list[0].astext() - '--no-color' - """ - options = normalize_options(options) - node = nodes.literal(rawtext, text, classes=["cli-option"]) - - if text.startswith("--"): - node["classes"].append("cli-option-long") - elif text.startswith("-"): - node["classes"].append("cli-option-short") - - return [node], [] - - -def cli_metavar_role( - name: str, - rawtext: str, - text: str, - lineno: int, - inliner: Inliner | None, - options: dict[str, t.Any] | None = None, - content: list[str] | None = None, -) -> tuple[list[nodes.Node], list[nodes.system_message]]: - """Role for CLI metavar placeholders like FILE or PATH. - - Generates a literal node with 'cli-metavar' CSS class for styling. - - Parameters - ---------- - name : str - Local name of the role used in document. - rawtext : str - Full interpreted text including role markup. - text : str - Content between backticks. - lineno : int - Line number. - inliner : Inliner | None - Object that called the role. - options : dict | None - Options from role directive. - content : list | None - Content from role directive. - - Returns - ------- - tuple[list[nodes.Node], list[nodes.system_message]] - Nodes to insert and any messages. - - Examples - -------- - >>> node_list, messages = cli_metavar_role( - ... "cli-metavar", ":cli-metavar:`FILE`", "FILE", - ... 1, None - ... ) - >>> node_list[0]["classes"] - ['cli-metavar'] - >>> node_list[0].astext() - 'FILE' - - >>> node_list, messages = cli_metavar_role( - ... "cli-metavar", ":cli-metavar:`PATH`", "PATH", - ... 1, None - ... ) - >>> "cli-metavar" in node_list[0]["classes"] - True - """ - options = normalize_options(options) - node = nodes.literal(rawtext, text, classes=["cli-metavar"]) - return [node], [] - - -def cli_command_role( - name: str, - rawtext: str, - text: str, - lineno: int, - inliner: Inliner | None, - options: dict[str, t.Any] | None = None, - content: list[str] | None = None, -) -> tuple[list[nodes.Node], list[nodes.system_message]]: - """Role for CLI command names like sync or add. - - Generates a literal node with 'cli-command' CSS class for styling. - - Parameters - ---------- - name : str - Local name of the role used in document. - rawtext : str - Full interpreted text including role markup. - text : str - Content between backticks. - lineno : int - Line number. - inliner : Inliner | None - Object that called the role. - options : dict | None - Options from role directive. - content : list | None - Content from role directive. - - Returns - ------- - tuple[list[nodes.Node], list[nodes.system_message]] - Nodes to insert and any messages. - - Examples - -------- - >>> node_list, messages = cli_command_role( - ... "cli-command", ":cli-command:`sync`", "sync", - ... 1, None - ... ) - >>> node_list[0]["classes"] - ['cli-command'] - >>> node_list[0].astext() - 'sync' - - >>> node_list, messages = cli_command_role( - ... "cli-command", ":cli-command:`myapp`", "myapp", - ... 1, None - ... ) - >>> "cli-command" in node_list[0]["classes"] - True - """ - options = normalize_options(options) - node = nodes.literal(rawtext, text, classes=["cli-command"]) - return [node], [] - - -def cli_default_role( - name: str, - rawtext: str, - text: str, - lineno: int, - inliner: Inliner | None, - options: dict[str, t.Any] | None = None, - content: list[str] | None = None, -) -> tuple[list[nodes.Node], list[nodes.system_message]]: - """Role for CLI default values like None or "default". - - Generates a literal node with 'cli-default' CSS class for styling. - - Parameters - ---------- - name : str - Local name of the role used in document. - rawtext : str - Full interpreted text including role markup. - text : str - Content between backticks. - lineno : int - Line number. - inliner : Inliner | None - Object that called the role. - options : dict | None - Options from role directive. - content : list | None - Content from role directive. - - Returns - ------- - tuple[list[nodes.Node], list[nodes.system_message]] - Nodes to insert and any messages. - - Examples - -------- - >>> node_list, messages = cli_default_role( - ... "cli-default", ":cli-default:`None`", "None", - ... 1, None - ... ) - >>> node_list[0]["classes"] - ['cli-default'] - >>> node_list[0].astext() - 'None' - - >>> node_list, messages = cli_default_role( - ... "cli-default", ':cli-default:`"auto"`', '"auto"', - ... 1, None - ... ) - >>> "cli-default" in node_list[0]["classes"] - True - """ - options = normalize_options(options) - node = nodes.literal(rawtext, text, classes=["cli-default"]) - return [node], [] - - -def cli_choice_role( - name: str, - rawtext: str, - text: str, - lineno: int, - inliner: Inliner | None, - options: dict[str, t.Any] | None = None, - content: list[str] | None = None, -) -> tuple[list[nodes.Node], list[nodes.system_message]]: - """Role for CLI choice values like json or yaml. - - Generates a literal node with 'cli-choice' CSS class for styling. - - Parameters - ---------- - name : str - Local name of the role used in document. - rawtext : str - Full interpreted text including role markup. - text : str - Content between backticks. - lineno : int - Line number. - inliner : Inliner | None - Object that called the role. - options : dict | None - Options from role directive. - content : list | None - Content from role directive. - - Returns - ------- - tuple[list[nodes.Node], list[nodes.system_message]] - Nodes to insert and any messages. - - Examples - -------- - >>> node_list, messages = cli_choice_role( - ... "cli-choice", ":cli-choice:`json`", "json", - ... 1, None - ... ) - >>> node_list[0]["classes"] - ['cli-choice'] - >>> node_list[0].astext() - 'json' - - >>> node_list, messages = cli_choice_role( - ... "cli-choice", ":cli-choice:`yaml`", "yaml", - ... 1, None - ... ) - >>> "cli-choice" in node_list[0]["classes"] - True - """ - options = normalize_options(options) - node = nodes.literal(rawtext, text, classes=["cli-choice"]) - return [node], [] - - -def register_roles() -> None: - """Register all CLI roles with docutils. - - This function registers the following roles: - - cli-option: For CLI options (--verbose, -h) - - cli-metavar: For metavar placeholders (FILE, PATH) - - cli-command: For command names (sync, add) - - cli-default: For default values (None, "default") - - cli-choice: For choice values (json, yaml) - - Examples - -------- - >>> register_roles() - >>> # Roles are now available in docutils RST parsing - """ - roles.register_local_role("cli-option", cli_option_role) # type: ignore[arg-type] - roles.register_local_role("cli-metavar", cli_metavar_role) # type: ignore[arg-type] - roles.register_local_role("cli-command", cli_command_role) # type: ignore[arg-type] - roles.register_local_role("cli-default", cli_default_role) # type: ignore[arg-type] - roles.register_local_role("cli-choice", cli_choice_role) # type: ignore[arg-type] diff --git a/docs/_ext/cli_usage_lexer.py b/docs/_ext/cli_usage_lexer.py deleted file mode 100644 index 40170e3178..0000000000 --- a/docs/_ext/cli_usage_lexer.py +++ /dev/null @@ -1,115 +0,0 @@ -"""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 - -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 - -------- - >>> 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: list[str] = [] # noqa: RUF012 - mimetypes = ["text/x-cli-usage"] # noqa: RUF012 - - tokens = { # noqa: RUF012 - "root": [ - # "usage:" at start of line - (r"^(usage:)(\s+)", bygroups(Generic.Heading, Whitespace)), # type: ignore[no-untyped-call] - # 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), # type: ignore[no-untyped-call] - ), - # 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), # type: ignore[no-untyped-call] - ), - # 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) - ] diff --git a/docs/_ext/sphinx_argparse_neo/__init__.py b/docs/_ext/sphinx_argparse_neo/__init__.py deleted file mode 100644 index 5fa8dd94fe..0000000000 --- a/docs/_ext/sphinx_argparse_neo/__init__.py +++ /dev/null @@ -1,101 +0,0 @@ -"""sphinx_argparse_neo - 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_argparse_neo.directive import ArgparseDirective -from sphinx_argparse_neo.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_argparse_neo.utils import strip_ansi - -__all__ = [ - "ArgparseDirective", - "strip_ansi", -] - -if t.TYPE_CHECKING: - from sphinx.application import Sphinx - -__version__ = "1.0.0" - - -def setup(app: Sphinx) -> dict[str, t.Any]: - """Register the argparse directive and configuration options. - - Parameters - ---------- - app : Sphinx - The Sphinx application object. - - Returns - ------- - dict[str, t.Any] - Extension metadata. - """ - # Configuration options - app.add_config_value("argparse_group_title_prefix", "", "html") - app.add_config_value("argparse_show_defaults", True, "html") - app.add_config_value("argparse_show_choices", True, "html") - app.add_config_value("argparse_show_types", True, "html") - - # 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 directive - app.add_directive("argparse", ArgparseDirective) - - return { - "version": __version__, - "parallel_read_safe": True, - "parallel_write_safe": True, - } diff --git a/docs/_ext/sphinx_argparse_neo/compat.py b/docs/_ext/sphinx_argparse_neo/compat.py deleted file mode 100644 index 15816d574c..0000000000 --- a/docs/_ext/sphinx_argparse_neo/compat.py +++ /dev/null @@ -1,271 +0,0 @@ -"""Compatibility utilities for module loading. - -This module provides utilities for loading Python modules safely, -including mock handling for imports that may fail during documentation -builds. - -Unlike sphinx-argparse, this module does NOT depend on autodoc's mock -functionality, which moved in Sphinx 9.x. -""" - -from __future__ import annotations - -import contextlib -import importlib -import sys -import typing as t - -if t.TYPE_CHECKING: - import argparse - from collections.abc import Iterator - - -class MockModule: - """Simple mock for unavailable imports. - - This class provides a minimal mock that can be used as a placeholder - for modules that aren't available during documentation builds. - - Parameters - ---------- - name : str - The module name being mocked. - - Examples - -------- - >>> mock = MockModule("mypackage.submodule") - >>> mock.__name__ - 'mypackage.submodule' - >>> child = mock.child_attr - >>> child.__name__ - 'mypackage.submodule.child_attr' - >>> callable(mock.some_function) - True - >>> mock.some_function() - - """ - - def __init__(self, name: str) -> None: - """Initialize the mock module.""" - self.__name__ = name - self._name = name - - def __repr__(self) -> str: - """Return string representation.""" - return f"" - - def __getattr__(self, name: str) -> MockModule: - """Return a child mock for any attribute access. - - Parameters - ---------- - name : str - The attribute name. - - Returns - ------- - MockModule - A new mock for the child attribute. - """ - return MockModule(f"{self._name}.{name}") - - def __call__(self, *args: t.Any, **kwargs: t.Any) -> MockModule: - """Return self when called as a function. - - Parameters - ---------- - *args : t.Any - Positional arguments (ignored). - **kwargs : t.Any - Keyword arguments (ignored). - - Returns - ------- - MockModule - Self. - """ - return self - - -@contextlib.contextmanager -def mock_imports(modules: list[str]) -> Iterator[None]: - """Context manager to mock missing imports. - - This provides a simple way to temporarily add mock modules to - sys.modules, allowing imports to succeed during documentation builds - even when the actual modules aren't available. - - Parameters - ---------- - modules : list[str] - List of module names to mock. - - Yields - ------ - None - Context manager yields nothing. - - Examples - -------- - >>> import sys - >>> "fake_module" in sys.modules - False - >>> with mock_imports(["fake_module", "fake_module.sub"]): - ... import fake_module - ... fake_module.__name__ - 'fake_module' - >>> "fake_module" in sys.modules - False - """ - mocked: dict[str, MockModule] = {} - - for name in modules: - if name not in sys.modules: - mocked[name] = MockModule(name) - sys.modules[name] = mocked[name] # type: ignore[assignment] - - try: - yield - finally: - for name in mocked: - del sys.modules[name] - - -def import_module(module_name: str) -> t.Any: - """Import a module by name. - - Parameters - ---------- - module_name : str - The fully qualified module name. - - Returns - ------- - t.Any - The imported module. - - Raises - ------ - ImportError - If the module cannot be imported. - - Examples - -------- - >>> mod = import_module("argparse") - >>> hasattr(mod, "ArgumentParser") - True - """ - return importlib.import_module(module_name) - - -def get_parser_from_module( - module_name: str, - func_name: str, - mock_modules: list[str] | None = None, -) -> argparse.ArgumentParser: - """Import a module and call a function to get an ArgumentParser. - - Parameters - ---------- - module_name : str - The module containing the parser factory function. - func_name : str - The name of the function that returns an ArgumentParser. - Can be a dotted path like "Class.method". - mock_modules : list[str] | None - Optional list of module names to mock during import. - - Returns - ------- - argparse.ArgumentParser - The argument parser returned by the function. - - Raises - ------ - ImportError - If the module cannot be imported. - AttributeError - If the function is not found. - TypeError - If the function doesn't return an ArgumentParser. - - Examples - -------- - Load tmuxp's parser factory: - - >>> parser = get_parser_from_module("tmuxp.cli", "create_parser") - >>> parser.prog - 'tmuxp' - >>> hasattr(parser, 'parse_args') - True - """ - ctx = mock_imports(mock_modules) if mock_modules else contextlib.nullcontext() - - with ctx: - module = import_module(module_name) - - # Handle dotted paths like "Class.method" - obj = module - for part in func_name.split("."): - obj = getattr(obj, part) - - # Call the function if it's callable - parser = obj() if callable(obj) else obj - - # Validate the return type at runtime - import argparse as argparse_module - - if not isinstance(parser, argparse_module.ArgumentParser): - msg = ( - f"{module_name}:{func_name} returned {type(parser).__name__}, " - f"expected ArgumentParser" - ) - raise TypeError(msg) - - return parser - - -def get_parser_from_entry_point( - entry_point: str, - mock_modules: list[str] | None = None, -) -> argparse.ArgumentParser: - """Get an ArgumentParser from a setuptools-style entry point string. - - Parameters - ---------- - entry_point : str - Entry point in the format "module:function" or "module:Class.method". - mock_modules : list[str] | None - Optional list of module names to mock during import. - - Returns - ------- - argparse.ArgumentParser - The argument parser. - - Raises - ------ - ValueError - If the entry point format is invalid. - - Examples - -------- - Load tmuxp's parser using entry point syntax: - - >>> parser = get_parser_from_entry_point("tmuxp.cli:create_parser") - >>> parser.prog - 'tmuxp' - - Invalid format raises ValueError: - - >>> get_parser_from_entry_point("no_colon") - Traceback (most recent call last): - ... - ValueError: Invalid entry point format: 'no_colon'. Expected 'module:function' - """ - if ":" not in entry_point: - msg = f"Invalid entry point format: {entry_point!r}. Expected 'module:function'" - raise ValueError(msg) - - module_name, func_name = entry_point.split(":", 1) - return get_parser_from_module(module_name, func_name, mock_modules) diff --git a/docs/_ext/sphinx_argparse_neo/directive.py b/docs/_ext/sphinx_argparse_neo/directive.py deleted file mode 100644 index 80d6d155ab..0000000000 --- a/docs/_ext/sphinx_argparse_neo/directive.py +++ /dev/null @@ -1,240 +0,0 @@ -"""Sphinx directive for argparse documentation. - -This module provides the ArgparseDirective class that integrates -with Sphinx to generate documentation from ArgumentParser instances. -""" - -from __future__ import annotations - -import typing as t - -from docutils import nodes -from docutils.parsers.rst import directives -from sphinx.util.docutils import SphinxDirective -from sphinx_argparse_neo.compat import get_parser_from_module -from sphinx_argparse_neo.parser import extract_parser -from sphinx_argparse_neo.renderer import ArgparseRenderer, RenderConfig - -if t.TYPE_CHECKING: - import argparse - - -class ArgparseDirective(SphinxDirective): - """Sphinx directive for documenting argparse-based CLI tools. - - Usage - ----- - .. argparse:: - :module: myapp.cli - :func: create_parser - :prog: myapp - - Options - ------- - :module: - The Python module containing the parser factory function. - :func: - The function name that returns an ArgumentParser. - Can be a dotted path like "Class.method". - :prog: - Override the program name (optional). - :path: - Navigate to a specific subparser by path (e.g., "sync pull"). - :no-defaults: - Don't show default values (flag). - :no-description: - Don't show parser description (flag). - :no-epilog: - Don't show parser epilog (flag). - :mock-modules: - Comma-separated list of modules to mock during import. - - Examples - -------- - In RST documentation:: - - .. argparse:: - :module: myapp.cli - :func: create_parser - :prog: myapp - - :path: subcommand - """ - - has_content = True - required_arguments = 0 - optional_arguments = 0 - - option_spec: t.ClassVar[dict[str, t.Any]] = { - "module": directives.unchanged_required, - "func": directives.unchanged_required, - "prog": directives.unchanged, - "path": directives.unchanged, - "no-defaults": directives.flag, - "no-description": directives.flag, - "no-epilog": directives.flag, - "no-choices": directives.flag, - "no-types": directives.flag, - "mock-modules": directives.unchanged, - # sphinx-argparse compatibility options - "nosubcommands": directives.flag, - "nodefault": directives.flag, - "noepilog": directives.flag, - "nodescription": directives.flag, - } - - def run(self) -> list[nodes.Node]: - """Execute the directive and return docutils nodes. - - Returns - ------- - list[nodes.Node] - List of docutils nodes representing the CLI documentation. - """ - # Get required options - module_name = self.options.get("module") - func_name = self.options.get("func") - - if not module_name or not func_name: - error = self.state_machine.reporter.error( - "argparse directive requires :module: and :func: options", - line=self.lineno, - ) - return [error] - - # Parse mock modules - mock_modules: list[str] | None = None - if "mock-modules" in self.options: - mock_modules = [m.strip() for m in self.options["mock-modules"].split(",")] - - # Load the parser - try: - parser = get_parser_from_module(module_name, func_name, mock_modules) - except Exception as e: - error = self.state_machine.reporter.error( - f"Failed to load parser from {module_name}:{func_name}: {e}", - line=self.lineno, - ) - return [error] - - # Override prog if specified - if "prog" in self.options: - parser.prog = self.options["prog"] - - # Navigate to subparser if path specified - if "path" in self.options: - parser = self._navigate_to_subparser(parser, self.options["path"]) - if parser is None: - error = self.state_machine.reporter.error( - f"Subparser path not found: {self.options['path']}", - line=self.lineno, - ) - return [error] - - # Build render config from directive options and Sphinx config - config = self._build_render_config() - - # Extract parser info - parser_info = extract_parser(parser) - - # Apply directive-level overrides - # Handle both new-style and sphinx-argparse compatibility options - if "no-description" in self.options or "nodescription" in self.options: - parser_info = parser_info.__class__( - prog=parser_info.prog, - usage=parser_info.usage, - bare_usage=parser_info.bare_usage, - description=None, - epilog=parser_info.epilog, - argument_groups=parser_info.argument_groups, - subcommands=parser_info.subcommands, - subcommand_dest=parser_info.subcommand_dest, - ) - if "no-epilog" in self.options or "noepilog" in self.options: - parser_info = parser_info.__class__( - prog=parser_info.prog, - usage=parser_info.usage, - bare_usage=parser_info.bare_usage, - description=parser_info.description, - epilog=None, - argument_groups=parser_info.argument_groups, - subcommands=parser_info.subcommands, - subcommand_dest=parser_info.subcommand_dest, - ) - if "nosubcommands" in self.options: - parser_info = parser_info.__class__( - prog=parser_info.prog, - usage=parser_info.usage, - bare_usage=parser_info.bare_usage, - description=parser_info.description, - epilog=parser_info.epilog, - argument_groups=parser_info.argument_groups, - subcommands=None, - subcommand_dest=None, - ) - - # Render to nodes - renderer = ArgparseRenderer(config=config, state=self.state) - return t.cast(list[nodes.Node], renderer.render(parser_info)) - - def _build_render_config(self) -> RenderConfig: - """Build RenderConfig from directive and Sphinx config options. - - Returns - ------- - RenderConfig - Configuration for the renderer. - """ - # Start with Sphinx config defaults - config = RenderConfig.from_sphinx_config(self.config) - - # Override with directive options - # Handle both new-style and sphinx-argparse compatibility options - if "no-defaults" in self.options or "nodefault" in self.options: - config.show_defaults = False - if "no-choices" in self.options: - config.show_choices = False - if "no-types" in self.options: - config.show_types = False - - return config - - def _navigate_to_subparser( - self, parser: argparse.ArgumentParser, path: str - ) -> argparse.ArgumentParser | None: - """Navigate to a nested subparser by path. - - Parameters - ---------- - parser : argparse.ArgumentParser - The root parser. - path : str - Space-separated path to the subparser (e.g., "sync pull"). - - Returns - ------- - argparse.ArgumentParser | None - The subparser, or None if not found. - """ - import argparse as argparse_module - - current = parser - for name in path.split(): - # Find subparsers action - subparser_action = None - for action in current._actions: - if isinstance(action, argparse_module._SubParsersAction): - subparser_action = action - break - - if subparser_action is None: - return None - - # Find the named subparser - choices = subparser_action.choices or {} - if name not in choices: - return None - - current = choices[name] - - return current diff --git a/docs/_ext/sphinx_argparse_neo/nodes.py b/docs/_ext/sphinx_argparse_neo/nodes.py deleted file mode 100644 index 468b5876a5..0000000000 --- a/docs/_ext/sphinx_argparse_neo/nodes.py +++ /dev/null @@ -1,647 +0,0 @@ -"""Custom docutils node types for argparse documentation. - -This module defines custom node types that represent the structure of -CLI documentation, along with HTML visitor functions for rendering. -""" - -from __future__ import annotations - -import typing as t - -from docutils import nodes - -if t.TYPE_CHECKING: - from sphinx.writers.html5 import HTML5Translator - -# Import the lexer - use absolute import from parent package -import pathlib -import sys - -# Add parent directory to path for lexer import -_ext_dir = pathlib.Path(__file__).parent.parent -if str(_ext_dir) not in sys.path: - sys.path.insert(0, str(_ext_dir)) - -from argparse_lexer import ArgparseUsageLexer # noqa: E402 -from sphinx_argparse_neo.utils import strip_ansi # noqa: E402 - - -def _generate_argument_id(names: list[str], id_prefix: str = "") -> str: - """Generate unique ID for an argument based on its names. - - Creates a slug-style ID suitable for HTML anchors by: - 1. Stripping leading dashes from option names - 2. Joining multiple names with hyphens - 3. Prepending optional prefix for namespace isolation - - Parameters - ---------- - names : list[str] - List of argument names (e.g., ["-L", "--socket-name"]). - id_prefix : str - Optional prefix for uniqueness (e.g., "shell" -> "shell-L-socket-name"). - - Returns - ------- - str - A slug-style ID suitable for HTML anchors. - - Examples - -------- - >>> _generate_argument_id(["-L"]) - 'L' - >>> _generate_argument_id(["--help"]) - 'help' - >>> _generate_argument_id(["-v", "--verbose"]) - 'v-verbose' - >>> _generate_argument_id(["-L"], "shell") - 'shell-L' - >>> _generate_argument_id(["filename"]) - 'filename' - >>> _generate_argument_id([]) - '' - """ - clean_names = [name.lstrip("-") for name in names if name.lstrip("-")] - if not clean_names: - return "" - name_part = "-".join(clean_names) - return f"{id_prefix}-{name_part}" if id_prefix else name_part - - -def _token_to_css_class(token_type: t.Any) -> str: - """Map a Pygments token type to its CSS class abbreviation. - - Pygments uses hierarchical token names like Token.Name.Attribute. - These map to CSS classes using abbreviations of the last two parts: - - Token.Name.Attribute → 'na' (Name.Attribute) - - Token.Generic.Heading → 'gh' (Generic.Heading) - - Token.Punctuation → 'p' (just Punctuation) - - Parameters - ---------- - token_type : Any - A Pygments token type (from pygments.token). - - Returns - ------- - str - CSS class abbreviation, or empty string if not mappable. - - Examples - -------- - >>> from pygments.token import Token - >>> _token_to_css_class(Token.Name.Attribute) - 'na' - >>> _token_to_css_class(Token.Generic.Heading) - 'gh' - >>> _token_to_css_class(Token.Punctuation) - 'p' - >>> _token_to_css_class(Token.Text.Whitespace) - 'tw' - """ - type_str = str(token_type) - # Token string looks like "Token.Name.Attribute" or "Token.Punctuation" - parts = type_str.split(".") - - if len(parts) >= 3: - # Token.Name.Attribute -> "na" (first char of each of last two parts) - return parts[-2][0].lower() + parts[-1][0].lower() - elif len(parts) == 2: - # Token.Punctuation -> "p" (first char of last part) - return parts[-1][0].lower() - return "" - - -def _highlight_usage(usage_text: str, encode: t.Callable[[str], str]) -> str: - """Tokenize usage text and wrap tokens in highlighted span elements. - - Uses ArgparseUsageLexer to tokenize the usage string, then wraps each - token in a with the appropriate CSS class for styling. - - Parameters - ---------- - usage_text : str - The usage string to highlight (should include "usage: " prefix). - encode : Callable[[str], str] - HTML encoding function (typically translator.encode). - - Returns - ------- - str - HTML string with tokens wrapped in styled elements. - - Examples - -------- - >>> def mock_encode(s: str) -> str: - ... return s.replace("&", "&").replace("<", "<") - >>> html = _highlight_usage("usage: cmd [-h]", mock_encode) - >>> 'usage:' in html - True - >>> 'cmd' in html - True - >>> '-h' in html - True - """ - lexer = ArgparseUsageLexer() - parts: list[str] = [] - - for tok_type, tok_value in lexer.get_tokens(usage_text): - if not tok_value: - continue - - css_class = _token_to_css_class(tok_type) - escaped = encode(tok_value) - type_str = str(tok_type).lower() - - # Skip wrapping for whitespace and plain text tokens - if css_class and "whitespace" not in type_str and "text" not in type_str: - parts.append(f'{escaped}') - else: - parts.append(escaped) - - return "".join(parts) - - -def _highlight_argument_names( - names: list[str], metavar: str | None, encode: t.Callable[[str], str] -) -> str: - """Highlight argument names and metavar with appropriate CSS classes. - - Short options (-h) get class 'na' (Name.Attribute). - Long options (--help) get class 'nt' (Name.Tag). - Positional arguments get class 'nl' (Name.Label). - Metavars get class 'nv' (Name.Variable). - - Parameters - ---------- - names : list[str] - List of argument names (e.g., ["-v", "--verbose"]). - metavar : str | None - Optional metavar (e.g., "FILE", "PATH"). - encode : Callable[[str], str] - HTML encoding function. - - Returns - ------- - str - HTML string with highlighted argument signature. - - Examples - -------- - >>> def mock_encode(s: str) -> str: - ... return s - >>> html = _highlight_argument_names(["-h", "--help"], None, mock_encode) - >>> '-h' in html - True - >>> '--help' in html - True - >>> html = _highlight_argument_names(["--output"], "FILE", mock_encode) - >>> 'FILE' in html - True - >>> html = _highlight_argument_names(["sync"], None, mock_encode) - >>> 'sync' in html - True - """ - sig_parts: list[str] = [] - - for name in names: - escaped = encode(name) - if name.startswith("--"): - sig_parts.append(f'{escaped}') - elif name.startswith("-"): - sig_parts.append(f'{escaped}') - else: - # Positional argument or subcommand - sig_parts.append(f'{escaped}') - - result = ", ".join(sig_parts) - - if metavar: - escaped_metavar = encode(metavar) - result = f'{result} {escaped_metavar}' - - return result - - -class argparse_program(nodes.General, nodes.Element): - """Root node for an argparse program documentation block. - - Attributes - ---------- - prog : str - The program name. - - Examples - -------- - >>> node = argparse_program() - >>> node["prog"] = "myapp" - >>> node["prog"] - 'myapp' - """ - - pass - - -class argparse_usage(nodes.General, nodes.Element): - """Node for displaying program usage. - - Contains the usage string as a literal block. - - Examples - -------- - >>> node = argparse_usage() - >>> node["usage"] = "myapp [-h] [--verbose] command" - >>> node["usage"] - 'myapp [-h] [--verbose] command' - """ - - pass - - -class argparse_group(nodes.General, nodes.Element): - """Node for an argument group (positional, optional, or custom). - - Attributes - ---------- - title : str - The group title. - description : str | None - Optional group description. - - Examples - -------- - >>> node = argparse_group() - >>> node["title"] = "Output Options" - >>> node["title"] - 'Output Options' - """ - - pass - - -class argparse_argument(nodes.Part, nodes.Element): - """Node for a single CLI argument. - - Attributes - ---------- - names : list[str] - Argument names/flags. - help : str | None - Help text. - default : str | None - Default value string. - choices : list[str] | None - Available choices. - required : bool - Whether the argument is required. - metavar : str | None - Metavar for display. - - Examples - -------- - >>> node = argparse_argument() - >>> node["names"] = ["-v", "--verbose"] - >>> node["names"] - ['-v', '--verbose'] - """ - - pass - - -class argparse_subcommands(nodes.General, nodes.Element): - """Container node for subcommands section. - - Examples - -------- - >>> node = argparse_subcommands() - >>> node["title"] = "Commands" - >>> node["title"] - 'Commands' - """ - - pass - - -class argparse_subcommand(nodes.General, nodes.Element): - """Node for a single subcommand. - - Attributes - ---------- - name : str - Subcommand name. - aliases : list[str] - Subcommand aliases. - help : str | None - Subcommand help text. - - Examples - -------- - >>> node = argparse_subcommand() - >>> node["name"] = "sync" - >>> node["aliases"] = ["s"] - >>> node["name"] - 'sync' - """ - - pass - - -# HTML Visitor Functions - - -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'
\n') - - -def depart_argparse_program_html(self: HTML5Translator, node: argparse_program) -> None: - """Depart argparse_program node - close program container. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_program - The program node being departed. - """ - self.body.append("
\n") - - -def visit_argparse_usage_html(self: HTML5Translator, node: argparse_usage) -> None: - """Visit argparse_usage node - render usage block with syntax highlighting. - - The usage text is tokenized using ArgparseUsageLexer and wrapped in - styled elements for semantic highlighting of options, metavars, - commands, and punctuation. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_usage - The usage node being visited. - """ - usage = strip_ansi(node.get("usage", "")) - # Add both argparse-usage class and highlight class for CSS targeting - self.body.append('
')
-    # Prepend "usage: " and highlight the full usage string
-    highlighted = _highlight_usage(f"usage: {usage}", self.encode)
-    self.body.append(highlighted)
-
-
-def depart_argparse_usage_html(self: HTML5Translator, node: argparse_usage) -> None:
-    """Depart argparse_usage node - close usage block.
-
-    Parameters
-    ----------
-    self : HTML5Translator
-        The Sphinx HTML translator.
-    node : argparse_usage
-        The usage node being departed.
-    """
-    self.body.append("
\n") - - -def visit_argparse_group_html(self: HTML5Translator, node: argparse_group) -> None: - """Visit argparse_group node - start argument group. - - The title is now rendered by the parent section node, so this visitor - only handles the group container and description. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_group - The group node being visited. - """ - title = node.get("title", "") - group_id = title.lower().replace(" ", "-") if title else "arguments" - self.body.append(f'
\n') - # Title rendering removed - parent section now provides the heading - description = node.get("description") - if description: - self.body.append( - f'

{self.encode(description)}

\n' - ) - self.body.append('
\n') - - -def depart_argparse_group_html(self: HTML5Translator, node: argparse_group) -> None: - """Depart argparse_group node - close argument group. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_group - The group node being departed. - """ - self.body.append("
\n") - self.body.append("
\n") - - -def visit_argparse_argument_html( - self: HTML5Translator, node: argparse_argument -) -> None: - """Visit argparse_argument node - render argument entry with highlighting. - - Argument names are highlighted with semantic CSS classes: - - Short options (-h) get class 'na' (Name.Attribute) - - Long options (--help) get class 'nt' (Name.Tag) - - Positional arguments get class 'nl' (Name.Label) - - Metavars get class 'nv' (Name.Variable) - - The argument is wrapped in a container div with a unique ID for linking. - A headerlink anchor (¶) is added for direct navigation. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_argument - The argument node being visited. - """ - names: list[str] = node.get("names", []) - metavar = node.get("metavar") - id_prefix: str = node.get("id_prefix", "") - - # Generate unique ID for this argument - arg_id = _generate_argument_id(names, id_prefix) - - # Open wrapper div with ID for linking - if arg_id: - self.body.append(f'
\n') - else: - self.body.append('
\n') - - # Build the argument signature with syntax highlighting - highlighted_sig = _highlight_argument_names(names, metavar, self.encode) - - # Add headerlink anchor inside dt for navigation - headerlink = "" - if arg_id: - headerlink = f'' - - self.body.append( - f'
{highlighted_sig}{headerlink}
\n' - ) - self.body.append('
') - - # Add help text - help_text = node.get("help") - if help_text: - self.body.append(f"

{self.encode(help_text)}

") - - -def depart_argparse_argument_html( - self: HTML5Translator, node: argparse_argument -) -> None: - """Depart argparse_argument node - close argument entry. - - Adds default, choices, and type information if present. - Default values are wrapped in ```` for styled display. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_argument - The argument node being departed. - """ - # Build metadata as definition list items - default = node.get("default_string") - choices = node.get("choices") - type_name = node.get("type_name") - required = node.get("required", False) - - if default is not None or choices or type_name or required: - self.body.append('
\n') - - if default is not None: - self.body.append('
') - self.body.append('
Default
') - self.body.append( - f'
' - f'{self.encode(default)}
' - ) - self.body.append("
\n") - - if type_name: - self.body.append('
') - self.body.append('
Type
') - self.body.append( - f'
' - f'{self.encode(type_name)}
' - ) - self.body.append("
\n") - - if choices: - choices_str = ", ".join(str(c) for c in choices) - self.body.append('
') - self.body.append('
Choices
') - self.body.append( - f'
{self.encode(choices_str)}
' - ) - self.body.append("
\n") - - if required: - self.body.append('
Required
\n') - - self.body.append("
\n") - - self.body.append("
\n") - # Close wrapper div - self.body.append("
\n") - - -def visit_argparse_subcommands_html( - self: HTML5Translator, node: argparse_subcommands -) -> None: - """Visit argparse_subcommands node - start subcommands section. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_subcommands - The subcommands node being visited. - """ - title = node.get("title", "Sub-commands") - self.body.append('
\n') - self.body.append( - f'

{self.encode(title)}

\n' - ) - - -def depart_argparse_subcommands_html( - self: HTML5Translator, node: argparse_subcommands -) -> None: - """Depart argparse_subcommands node - close subcommands section. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_subcommands - The subcommands node being departed. - """ - self.body.append("
\n") - - -def visit_argparse_subcommand_html( - self: HTML5Translator, node: argparse_subcommand -) -> None: - """Visit argparse_subcommand node - start subcommand entry. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_subcommand - The subcommand node being visited. - """ - name = node.get("name", "") - aliases: list[str] = node.get("aliases", []) - - self.body.append(f'
\n') - - # Subcommand header - header = name - if aliases: - alias_str = ", ".join(aliases) - header = f"{name} ({alias_str})" - self.body.append( - f'

{self.encode(header)}

\n' - ) - - # Help text - help_text = node.get("help") - if help_text: - self.body.append( - f'

{self.encode(help_text)}

\n' - ) - - -def depart_argparse_subcommand_html( - self: HTML5Translator, node: argparse_subcommand -) -> None: - """Depart argparse_subcommand node - close subcommand entry. - - Parameters - ---------- - self : HTML5Translator - The Sphinx HTML translator. - node : argparse_subcommand - The subcommand node being departed. - """ - self.body.append("
\n") diff --git a/docs/_ext/sphinx_argparse_neo/parser.py b/docs/_ext/sphinx_argparse_neo/parser.py deleted file mode 100644 index f3a6db44af..0000000000 --- a/docs/_ext/sphinx_argparse_neo/parser.py +++ /dev/null @@ -1,659 +0,0 @@ -"""Argparse introspection - extract structured data from ArgumentParser. - -This module provides dataclasses and functions to introspect argparse -ArgumentParser instances and convert them into structured data suitable -for documentation rendering. -""" - -from __future__ import annotations - -import argparse -import dataclasses -import typing as t - -from sphinx_argparse_neo.utils import strip_ansi - -# Sentinel for "no default" (distinct from None which is a valid default) -NO_DEFAULT = object() - - -@dataclasses.dataclass -class ArgumentInfo: - """Represents a single CLI argument. - - Examples - -------- - >>> info = ArgumentInfo( - ... names=["-v", "--verbose"], - ... help="Enable verbose output", - ... default=False, - ... default_string="False", - ... choices=None, - ... required=False, - ... metavar=None, - ... nargs=None, - ... action="store_true", - ... type_name=None, - ... const=True, - ... dest="verbose", - ... ) - >>> info.names - ['-v', '--verbose'] - >>> info.is_positional - False - """ - - names: list[str] - help: str | None - default: t.Any - default_string: str | None - choices: list[t.Any] | None - required: bool - metavar: str | None - nargs: str | int | None - action: str - type_name: str | None - const: t.Any - dest: str - - @property - def is_positional(self) -> bool: - """Return True if this is a positional argument. - - Examples - -------- - >>> ArgumentInfo( - ... names=["filename"], - ... help=None, - ... default=None, - ... default_string=None, - ... choices=None, - ... required=True, - ... metavar=None, - ... nargs=None, - ... action="store", - ... type_name=None, - ... const=None, - ... dest="filename", - ... ).is_positional - True - >>> ArgumentInfo( - ... names=["-f", "--file"], - ... help=None, - ... default=None, - ... default_string=None, - ... choices=None, - ... required=False, - ... metavar=None, - ... nargs=None, - ... action="store", - ... type_name=None, - ... const=None, - ... dest="file", - ... ).is_positional - False - """ - return bool(self.names) and not self.names[0].startswith("-") - - -@dataclasses.dataclass -class MutuallyExclusiveGroup: - """Arguments that cannot be used together. - - Examples - -------- - >>> group = MutuallyExclusiveGroup(arguments=[], required=True) - >>> group.required - True - """ - - arguments: list[ArgumentInfo] - required: bool - - -@dataclasses.dataclass -class ArgumentGroup: - """Named group of arguments. - - Examples - -------- - >>> group = ArgumentGroup( - ... title="Output Options", - ... description="Control output format", - ... arguments=[], - ... mutually_exclusive=[], - ... ) - >>> group.title - 'Output Options' - """ - - title: str - description: str | None - arguments: list[ArgumentInfo] - mutually_exclusive: list[MutuallyExclusiveGroup] - - -@dataclasses.dataclass -class SubcommandInfo: - """A subparser/subcommand. - - Examples - -------- - >>> sub = SubcommandInfo( - ... name="sync", - ... aliases=["s"], - ... help="Synchronize repositories", - ... parser=None, # type: ignore[arg-type] - ... ) - >>> sub.aliases - ['s'] - """ - - name: str - aliases: list[str] - help: str | None - parser: ParserInfo # Recursive reference - - -@dataclasses.dataclass -class ParserInfo: - """Complete parsed ArgumentParser. - - Examples - -------- - >>> info = ParserInfo( - ... prog="myapp", - ... usage=None, - ... bare_usage="myapp [-h] command", - ... description="My application", - ... epilog=None, - ... argument_groups=[], - ... subcommands=None, - ... subcommand_dest=None, - ... ) - >>> info.prog - 'myapp' - """ - - prog: str - usage: str | None - bare_usage: str - description: str | None - epilog: str | None - argument_groups: list[ArgumentGroup] - subcommands: list[SubcommandInfo] | None - subcommand_dest: str | None - - -def _format_default(default: t.Any) -> str | None: - """Format a default value for display. - - Parameters - ---------- - default : t.Any - The default value to format. - - Returns - ------- - str | None - Formatted string representation, or None if suppressed/unset. - - Examples - -------- - >>> _format_default(None) - 'None' - >>> _format_default("hello") - 'hello' - >>> _format_default(42) - '42' - >>> _format_default(argparse.SUPPRESS) is None - True - >>> _format_default([1, 2, 3]) - '[1, 2, 3]' - """ - if default is argparse.SUPPRESS: - return None - if default is None: - return "None" - if isinstance(default, str): - return default - return repr(default) - - -def _get_type_name(action: argparse.Action) -> str | None: - """Extract the type name from an action. - - Parameters - ---------- - action : argparse.Action - The argparse action to inspect. - - Returns - ------- - str | None - The type name, or None if no type is specified. - - Examples - -------- - >>> parser = argparse.ArgumentParser() - >>> action = parser.add_argument("--count", type=int) - >>> _get_type_name(action) - 'int' - >>> action2 = parser.add_argument("--name") - >>> _get_type_name(action2) is None - True - """ - if action.type is None: - return None - if hasattr(action.type, "__name__"): - return action.type.__name__ - return str(action.type) - - -def _get_action_name(action: argparse.Action) -> str: - """Get the action type name. - - Parameters - ---------- - action : argparse.Action - The argparse action to inspect. - - Returns - ------- - str - The action type name. - - Examples - -------- - >>> parser = argparse.ArgumentParser() - >>> action = parser.add_argument("--verbose", action="store_true") - >>> _get_action_name(action) - 'store_true' - >>> action2 = parser.add_argument("--file") - >>> _get_action_name(action2) - 'store' - """ - # Map action classes to their string names - action_class = type(action).__name__ - action_map = { - "_StoreAction": "store", - "_StoreTrueAction": "store_true", - "_StoreFalseAction": "store_false", - "_StoreConstAction": "store_const", - "_AppendAction": "append", - "_AppendConstAction": "append_const", - "_CountAction": "count", - "_HelpAction": "help", - "_VersionAction": "version", - "_ExtendAction": "extend", - "BooleanOptionalAction": "boolean_optional", - } - return action_map.get(action_class, action_class.lower()) - - -def _extract_argument(action: argparse.Action) -> ArgumentInfo: - """Extract ArgumentInfo from an argparse Action. - - Parameters - ---------- - action : argparse.Action - The argparse action to extract information from. - - Returns - ------- - ArgumentInfo - Structured argument information. - - Examples - -------- - >>> parser = argparse.ArgumentParser() - >>> action = parser.add_argument( - ... "-v", "--verbose", - ... action="store_true", - ... help="Enable verbose mode", - ... ) - >>> info = _extract_argument(action) - >>> info.names - ['-v', '--verbose'] - >>> info.action - 'store_true' - """ - # Determine names - option_strings for optionals, dest for positionals - names = list(action.option_strings) if action.option_strings else [action.dest] - - # Determine if required - required = action.required if hasattr(action, "required") else False - # Positional arguments are required by default (unless nargs makes them optional) - if not action.option_strings: - required = action.nargs not in ("?", "*", argparse.REMAINDER) - - # Format metavar - metavar = action.metavar - if isinstance(metavar, tuple): - metavar = " ".join(metavar) - - # Handle default - default = action.default - default_string = _format_default(default) - - return ArgumentInfo( - names=names, - help=action.help if action.help != argparse.SUPPRESS else None, - default=default if default is not argparse.SUPPRESS else NO_DEFAULT, - default_string=default_string, - choices=list(action.choices) if action.choices else None, - required=required, - metavar=metavar, - nargs=action.nargs, - action=_get_action_name(action), - type_name=_get_type_name(action), - const=action.const, - dest=action.dest, - ) - - -def _extract_mutex_groups( - parser: argparse.ArgumentParser, -) -> dict[int, MutuallyExclusiveGroup]: - """Extract mutually exclusive groups from a parser. - - Parameters - ---------- - parser : argparse.ArgumentParser - The parser to extract from. - - Returns - ------- - dict[int, MutuallyExclusiveGroup] - Mapping from action id to the MutuallyExclusiveGroup it belongs to. - - Examples - -------- - Extract mutually exclusive groups from a parser with one group: - - >>> parser = argparse.ArgumentParser() - >>> group = parser.add_mutually_exclusive_group() - >>> _ = group.add_argument("--foo", help="Use foo") - >>> _ = group.add_argument("--bar", help="Use bar") - >>> mutex_map = _extract_mutex_groups(parser) - >>> len(mutex_map) - 2 - - Each action in the group maps to the same MutuallyExclusiveGroup: - - >>> values = list(mutex_map.values()) - >>> values[0] is values[1] - True - >>> len(values[0].arguments) - 2 - >>> [arg.names[0] for arg in values[0].arguments] - ['--foo', '--bar'] - - A parser without mutex groups returns an empty mapping: - - >>> parser2 = argparse.ArgumentParser() - >>> _ = parser2.add_argument("--verbose") - >>> _extract_mutex_groups(parser2) - {} - """ - mutex_map: dict[int, MutuallyExclusiveGroup] = {} - - for mutex_group in parser._mutually_exclusive_groups: - group_info = MutuallyExclusiveGroup( - arguments=[ - _extract_argument(action) - for action in mutex_group._group_actions - if action.help != argparse.SUPPRESS - ], - required=mutex_group.required, - ) - for action in mutex_group._group_actions: - mutex_map[id(action)] = group_info - - return mutex_map - - -def _extract_argument_groups( - parser: argparse.ArgumentParser, - hide_suppressed: bool = True, -) -> list[ArgumentGroup]: - """Extract argument groups from a parser. - - Parameters - ---------- - parser : argparse.ArgumentParser - The parser to extract from. - hide_suppressed : bool - Whether to hide arguments with SUPPRESS help. - - Returns - ------- - list[ArgumentGroup] - List of argument groups. - - Examples - -------- - >>> parser = argparse.ArgumentParser(description="Test") - >>> _ = parser.add_argument("filename", help="Input file") - >>> _ = parser.add_argument("-v", "--verbose", action="store_true") - >>> groups = _extract_argument_groups(parser) - >>> len(groups) >= 2 # positional and optional groups - True - """ - mutex_map = _extract_mutex_groups(parser) - seen_mutex: set[int] = set() - groups: list[ArgumentGroup] = [] - - for group in parser._action_groups: - arguments: list[ArgumentInfo] = [] - mutex_groups: list[MutuallyExclusiveGroup] = [] - - for action in group._group_actions: - # Skip help action and suppressed actions - if isinstance(action, argparse._HelpAction): - continue - if hide_suppressed and action.help == argparse.SUPPRESS: - continue - # Skip subparser actions - handled separately - if isinstance(action, argparse._SubParsersAction): - continue - - # Check if this action is in a mutex group - if id(action) in mutex_map: - mutex_info = mutex_map[id(action)] - mutex_id = id(mutex_info) - if mutex_id not in seen_mutex: - seen_mutex.add(mutex_id) - mutex_groups.append(mutex_info) - else: - arguments.append(_extract_argument(action)) - - # Skip empty groups - if not arguments and not mutex_groups: - continue - - groups.append( - ArgumentGroup( - title=group.title or "", - description=group.description, - arguments=arguments, - mutually_exclusive=mutex_groups, - ) - ) - - return groups - - -def _extract_subcommands( - parser: argparse.ArgumentParser, - hide_suppressed: bool = True, -) -> tuple[list[SubcommandInfo] | None, str | None]: - """Extract subcommands from a parser. - - Parameters - ---------- - parser : argparse.ArgumentParser - The parser to extract from. - hide_suppressed : bool - Whether to hide subcommands with SUPPRESS help. - - Returns - ------- - tuple[list[SubcommandInfo] | None, str | None] - Tuple of (subcommands list, destination variable name). - - Examples - -------- - >>> parser = argparse.ArgumentParser() - >>> subparsers = parser.add_subparsers(dest="command") - >>> _ = subparsers.add_parser("sync", help="Sync repos") - >>> _ = subparsers.add_parser("add", help="Add repo") - >>> subs, dest = _extract_subcommands(parser) - >>> dest - 'command' - >>> len(subs) - 2 - """ - for action in parser._actions: - if isinstance(action, argparse._SubParsersAction): - subcommands: list[SubcommandInfo] = [] - - # Get the choices (subparsers) - choices = action.choices or {} - - # Build reverse mapping of aliases - # action._parser_class might have name_parser_map with aliases - alias_map: dict[str, list[str]] = {} - seen_parsers: dict[int, str] = {} - - for name, subparser in choices.items(): - parser_id = id(subparser) - if parser_id in seen_parsers: - # This is an alias - primary = seen_parsers[parser_id] - if primary not in alias_map: - alias_map[primary] = [] - alias_map[primary].append(name) - else: - seen_parsers[parser_id] = name - - # Now extract subcommand info - processed: set[int] = set() - for name, subparser in choices.items(): - parser_id = id(subparser) - if parser_id in processed: - continue - processed.add(parser_id) - - # Get help text - help_text: str | None = None - if hasattr(action, "_choices_actions"): - for choice_action in action._choices_actions: - if choice_action.dest == name: - help_text = choice_action.help - break - - if hide_suppressed and help_text == argparse.SUPPRESS: - continue - - # Recursively extract parser info - sub_info = extract_parser(subparser, hide_suppressed=hide_suppressed) - - subcommands.append( - SubcommandInfo( - name=name, - aliases=alias_map.get(name, []), - help=help_text, - parser=sub_info, - ) - ) - - return subcommands, action.dest - - return None, None - - -def _generate_usage(parser: argparse.ArgumentParser) -> str: - """Generate the usage string for a parser. - - Parameters - ---------- - parser : argparse.ArgumentParser - The parser to generate usage for. - - Returns - ------- - str - The bare usage string (without "usage: " prefix). - - Examples - -------- - >>> parser = argparse.ArgumentParser(prog="myapp") - >>> _ = parser.add_argument("-v", "--verbose", action="store_true") - >>> usage = _generate_usage(parser) - >>> "myapp" in usage - True - """ - # Use argparse's built-in formatter to generate usage - formatter = parser._get_formatter() - formatter.add_usage( - parser.usage, parser._actions, parser._mutually_exclusive_groups - ) - usage: str = formatter.format_help().strip() - - # Strip ANSI codes before checking prefix (handles FORCE_COLOR edge case) - usage = strip_ansi(usage) - - # Remove "usage: " prefix if present - if usage.lower().startswith("usage:"): - usage = usage[6:].strip() - - return usage - - -def extract_parser( - parser: argparse.ArgumentParser, - hide_suppressed: bool = True, -) -> ParserInfo: - """Extract complete parser information. - - Parameters - ---------- - parser : argparse.ArgumentParser - The parser to extract information from. - hide_suppressed : bool - Whether to hide arguments/subcommands with SUPPRESS help. - - Returns - ------- - ParserInfo - Complete structured parser information. - - Examples - -------- - >>> parser = argparse.ArgumentParser( - ... prog="myapp", - ... description="My application", - ... ) - >>> _ = parser.add_argument("filename", help="Input file") - >>> _ = parser.add_argument("-v", "--verbose", action="store_true") - >>> info = extract_parser(parser) - >>> info.prog - 'myapp' - >>> info.description - 'My application' - >>> len(info.argument_groups) >= 1 - True - """ - subcommands, subcommand_dest = _extract_subcommands(parser, hide_suppressed) - - return ParserInfo( - prog=parser.prog, - usage=parser.usage, - bare_usage=_generate_usage(parser), - description=parser.description, - epilog=parser.epilog, - argument_groups=_extract_argument_groups(parser, hide_suppressed), - subcommands=subcommands, - subcommand_dest=subcommand_dest, - ) diff --git a/docs/_ext/sphinx_argparse_neo/renderer.py b/docs/_ext/sphinx_argparse_neo/renderer.py deleted file mode 100644 index f6c313f9f1..0000000000 --- a/docs/_ext/sphinx_argparse_neo/renderer.py +++ /dev/null @@ -1,604 +0,0 @@ -"""Renderer - convert ParserInfo to docutils nodes. - -This module provides the ArgparseRenderer class that transforms -structured parser information into docutils nodes for documentation. -""" - -from __future__ import annotations - -import dataclasses -import typing as t - -from docutils import nodes -from docutils.statemachine import StringList -from sphinx_argparse_neo.nodes import ( - argparse_argument, - argparse_group, - argparse_program, - argparse_subcommand, - argparse_subcommands, - argparse_usage, -) -from sphinx_argparse_neo.parser import ( - ArgumentGroup, - ArgumentInfo, - MutuallyExclusiveGroup, - ParserInfo, - SubcommandInfo, -) -from sphinx_argparse_neo.utils import escape_rst_emphasis - -if t.TYPE_CHECKING: - from docutils.parsers.rst.states import RSTState - from sphinx.config import Config - - -@dataclasses.dataclass -class RenderConfig: - """Configuration for the renderer. - - Examples - -------- - >>> config = RenderConfig() - >>> config.show_defaults - True - >>> config.group_title_prefix - '' - """ - - group_title_prefix: str = "" - show_defaults: bool = True - show_choices: bool = True - show_types: bool = True - - @classmethod - def from_sphinx_config(cls, config: Config) -> RenderConfig: - """Create RenderConfig from Sphinx configuration. - - Parameters - ---------- - config : Config - Sphinx configuration object. - - Returns - ------- - RenderConfig - Render configuration based on Sphinx config values. - """ - return cls( - group_title_prefix=getattr(config, "argparse_group_title_prefix", ""), - show_defaults=getattr(config, "argparse_show_defaults", True), - show_choices=getattr(config, "argparse_show_choices", True), - show_types=getattr(config, "argparse_show_types", True), - ) - - -class ArgparseRenderer: - """Render ParserInfo to docutils nodes. - - This class can be subclassed to customize rendering behavior. - Override individual methods to change how specific elements are rendered. - - Parameters - ---------- - config : RenderConfig - Rendering configuration. - state : RSTState | None - RST state for parsing nested RST content. - - Examples - -------- - >>> from sphinx_argparse_neo.parser import ParserInfo - >>> config = RenderConfig() - >>> renderer = ArgparseRenderer(config) - >>> info = ParserInfo( - ... prog="myapp", - ... usage=None, - ... bare_usage="myapp [-h]", - ... description="My app", - ... epilog=None, - ... argument_groups=[], - ... subcommands=None, - ... subcommand_dest=None, - ... ) - >>> result = renderer.render(info) - >>> isinstance(result, list) - True - """ - - def __init__( - self, - config: RenderConfig | None = None, - state: RSTState | None = None, - ) -> None: - """Initialize the renderer.""" - self.config = config or RenderConfig() - self.state = state - - @staticmethod - def _extract_id_prefix(prog: str) -> str: - """Extract subcommand from prog for unique section IDs. - - Parameters - ---------- - prog : str - The program name, potentially with subcommand (e.g., "tmuxp load"). - - Returns - ------- - str - The subcommand part for use as ID prefix, or empty string if none. - - Examples - -------- - >>> ArgparseRenderer._extract_id_prefix("tmuxp load") - 'load' - >>> ArgparseRenderer._extract_id_prefix("tmuxp") - '' - >>> ArgparseRenderer._extract_id_prefix("vcspull sync") - 'sync' - >>> ArgparseRenderer._extract_id_prefix("myapp sub cmd") - 'sub-cmd' - """ - parts = prog.split() - if len(parts) <= 1: - return "" - # Join remaining parts with hyphen for multi-level subcommands - return "-".join(parts[1:]) - - def render(self, parser_info: ParserInfo) -> list[nodes.Node]: - """Render a complete parser to docutils nodes. - - Parameters - ---------- - parser_info : ParserInfo - The parsed parser information. - - Returns - ------- - list[nodes.Node] - List of docutils nodes representing the documentation. - - Note - ---- - Sections for Usage and argument groups are emitted as siblings of - argparse_program rather than children. This allows Sphinx's - TocTreeCollector to discover them for inclusion in the table of - contents. - - The rendered structure is: - - - argparse_program (description only, no "examples:" part) - - section#usage (h3 "Usage" with usage block) - - section#positional-arguments (h3) - - section#options (h3) - - The "examples:" definition list in descriptions is left for - argparse_exemplar.py to transform into a proper Examples section. - """ - result: list[nodes.Node] = [] - - # Create program container for description only - program_node = argparse_program() - program_node["prog"] = parser_info.prog - - # Add description (may contain "examples:" definition list for later - # transformation by argparse_exemplar.py) - if parser_info.description: - desc_nodes = self._parse_text(parser_info.description) - program_node.extend(desc_nodes) - - result.append(program_node) - - # Extract ID prefix from prog for unique section IDs - # e.g., "tmuxp load" -> "load", "myapp" -> "" - id_prefix = self._extract_id_prefix(parser_info.prog) - - # Add Usage section as sibling (for TOC visibility) - usage_section = self.render_usage_section(parser_info, id_prefix=id_prefix) - result.append(usage_section) - - # Add argument groups as sibling sections (for TOC visibility) - for group in parser_info.argument_groups: - group_section = self.render_group_section(group, id_prefix=id_prefix) - result.append(group_section) - - # Add subcommands - if parser_info.subcommands: - subcommands_node = self.render_subcommands(parser_info.subcommands) - result.append(subcommands_node) - - # Add epilog - if parser_info.epilog: - epilog_nodes = self._parse_text(parser_info.epilog) - result.extend(epilog_nodes) - - return self.post_process(result) - - def render_usage(self, parser_info: ParserInfo) -> argparse_usage: - """Render the usage block. - - Parameters - ---------- - parser_info : ParserInfo - The parser information. - - Returns - ------- - argparse_usage - Usage node. - """ - usage_node = argparse_usage() - usage_node["usage"] = parser_info.bare_usage - return usage_node - - def render_usage_section( - self, parser_info: ParserInfo, *, id_prefix: str = "" - ) -> nodes.section: - """Render usage as a section with heading for TOC visibility. - - Creates a proper section node with "Usage" heading containing the - usage block. This structure allows Sphinx's TocTreeCollector to - discover it for the table of contents. - - Parameters - ---------- - parser_info : ParserInfo - The parser information. - id_prefix : str - Optional prefix for the section ID (e.g., "load" -> "load-usage"). - Used to ensure unique IDs when multiple argparse directives exist - on the same page. - - Returns - ------- - nodes.section - Section node containing the usage block with a "Usage" heading. - - Examples - -------- - >>> from sphinx_argparse_neo.parser import ParserInfo - >>> renderer = ArgparseRenderer() - >>> info = ParserInfo( - ... prog="myapp", - ... usage=None, - ... bare_usage="myapp [-h] command", - ... description=None, - ... epilog=None, - ... argument_groups=[], - ... subcommands=None, - ... subcommand_dest=None, - ... ) - >>> section = renderer.render_usage_section(info) - >>> section["ids"] - ['usage'] - - With prefix for subcommand pages: - - >>> section = renderer.render_usage_section(info, id_prefix="load") - >>> section["ids"] - ['load-usage'] - >>> section.children[0].astext() - 'Usage' - """ - section_id = f"{id_prefix}-usage" if id_prefix else "usage" - section = nodes.section() - section["ids"] = [section_id] - section["names"] = [nodes.fully_normalize_name("Usage")] - section += nodes.title("Usage", "Usage") - - usage_node = argparse_usage() - usage_node["usage"] = parser_info.bare_usage - section += usage_node - - return section - - def render_group_section( - self, group: ArgumentGroup, *, id_prefix: str = "" - ) -> nodes.section: - """Render an argument group wrapped in a section for TOC visibility. - - Creates a proper section node with the group title as heading, - containing the argparse_group node. This structure allows Sphinx's - TocTreeCollector to discover it for the table of contents. - - Parameters - ---------- - group : ArgumentGroup - The argument group to render. - id_prefix : str - Optional prefix for the section ID (e.g., "load" -> "load-options"). - Used to ensure unique IDs when multiple argparse directives exist - on the same page. - - Returns - ------- - nodes.section - Section node containing the group for TOC discovery. - - Examples - -------- - >>> from sphinx_argparse_neo.parser import ArgumentGroup - >>> renderer = ArgparseRenderer() - >>> group = ArgumentGroup( - ... title="positional arguments", - ... description=None, - ... arguments=[], - ... mutually_exclusive=[], - ... ) - >>> section = renderer.render_group_section(group) - >>> section["ids"] - ['positional-arguments'] - - With prefix for subcommand pages: - - >>> section = renderer.render_group_section(group, id_prefix="load") - >>> section["ids"] - ['load-positional-arguments'] - >>> section.children[0].astext() - 'Positional Arguments' - """ - # Title case the group title for proper display - raw_title = group.title or "Arguments" - title = raw_title.title() # "positional arguments" -> "Positional Arguments" - - if self.config.group_title_prefix: - title = f"{self.config.group_title_prefix}{title}" - - # Generate section ID from title (with optional prefix for uniqueness) - base_id = title.lower().replace(" ", "-") - section_id = f"{id_prefix}-{base_id}" if id_prefix else base_id - - # Create section wrapper for TOC discovery - section = nodes.section() - section["ids"] = [section_id] - section["names"] = [nodes.fully_normalize_name(title)] - - # Add title for TOC - Sphinx's TocTreeCollector looks for this - section += nodes.title(title, title) - - # Create the styled group container (with empty title - section provides it) - # Pass id_prefix to render_group so arguments get unique IDs - group_node = self.render_group(group, include_title=False, id_prefix=id_prefix) - section += group_node - - return section - - def render_group( - self, - group: ArgumentGroup, - include_title: bool = True, - *, - id_prefix: str = "", - ) -> argparse_group: - """Render an argument group. - - Parameters - ---------- - group : ArgumentGroup - The argument group to render. - include_title : bool - Whether to include the title in the group node. When False, - the title is assumed to come from a parent section node. - Default is True for backwards compatibility. - id_prefix : str - Optional prefix for argument IDs (e.g., "shell" -> "shell-h"). - Used to ensure unique IDs when multiple argparse directives exist - on the same page. - - Returns - ------- - argparse_group - Group node containing argument nodes. - """ - group_node = argparse_group() - - if include_title: - title = group.title - if self.config.group_title_prefix: - title = f"{self.config.group_title_prefix}{title}" - group_node["title"] = title - else: - # Title provided by parent section - group_node["title"] = "" - - group_node["description"] = group.description - - # Add individual arguments - for arg in group.arguments: - arg_node = self.render_argument(arg, id_prefix=id_prefix) - group_node.append(arg_node) - - # Add mutually exclusive groups - for mutex in group.mutually_exclusive: - mutex_nodes = self.render_mutex_group(mutex, id_prefix=id_prefix) - group_node.extend(mutex_nodes) - - return group_node - - def render_argument( - self, arg: ArgumentInfo, *, id_prefix: str = "" - ) -> argparse_argument: - """Render a single argument. - - Parameters - ---------- - arg : ArgumentInfo - The argument to render. - id_prefix : str - Optional prefix for the argument ID (e.g., "shell" -> "shell-L"). - Used to ensure unique IDs when multiple argparse directives exist - on the same page. - - Returns - ------- - argparse_argument - Argument node. - """ - arg_node = argparse_argument() - arg_node["names"] = arg.names - arg_node["help"] = arg.help - arg_node["metavar"] = arg.metavar - arg_node["required"] = arg.required - arg_node["id_prefix"] = id_prefix - - if self.config.show_defaults: - arg_node["default_string"] = arg.default_string - - if self.config.show_choices: - arg_node["choices"] = arg.choices - - if self.config.show_types: - arg_node["type_name"] = arg.type_name - - return arg_node - - def render_mutex_group( - self, mutex: MutuallyExclusiveGroup, *, id_prefix: str = "" - ) -> list[argparse_argument]: - """Render a mutually exclusive group. - - Parameters - ---------- - mutex : MutuallyExclusiveGroup - The mutually exclusive group. - id_prefix : str - Optional prefix for argument IDs (e.g., "shell" -> "shell-h"). - - Returns - ------- - list[argparse_argument] - List of argument nodes with mutex indicator. - """ - result: list[argparse_argument] = [] - for arg in mutex.arguments: - arg_node = self.render_argument(arg, id_prefix=id_prefix) - # Mark as part of mutex group - arg_node["mutex"] = True - arg_node["mutex_required"] = mutex.required - result.append(arg_node) - return result - - def render_subcommands( - self, subcommands: list[SubcommandInfo] - ) -> argparse_subcommands: - """Render subcommands section. - - Parameters - ---------- - subcommands : list[SubcommandInfo] - List of subcommand information. - - Returns - ------- - argparse_subcommands - Subcommands container node. - """ - container = argparse_subcommands() - container["title"] = "Sub-commands" - - for subcmd in subcommands: - subcmd_node = self.render_subcommand(subcmd) - container.append(subcmd_node) - - return container - - def render_subcommand(self, subcmd: SubcommandInfo) -> argparse_subcommand: - """Render a single subcommand. - - Parameters - ---------- - subcmd : SubcommandInfo - The subcommand information. - - Returns - ------- - argparse_subcommand - Subcommand node, potentially containing nested parser content. - """ - subcmd_node = argparse_subcommand() - subcmd_node["name"] = subcmd.name - subcmd_node["aliases"] = subcmd.aliases - subcmd_node["help"] = subcmd.help - - # Recursively render the subcommand's parser - if subcmd.parser: - nested_nodes = self.render(subcmd.parser) - subcmd_node.extend(nested_nodes) - - return subcmd_node - - def post_process(self, result_nodes: list[nodes.Node]) -> list[nodes.Node]: - """Post-process the rendered nodes. - - Override this method to apply transformations after rendering. - - Parameters - ---------- - result_nodes : list[nodes.Node] - The rendered nodes. - - Returns - ------- - list[nodes.Node] - Post-processed nodes. - """ - return result_nodes - - def _parse_text(self, text: str) -> list[nodes.Node]: - """Parse text as RST or MyST content. - - Parameters - ---------- - text : str - Text to parse. - - Returns - ------- - list[nodes.Node] - Parsed docutils nodes. - """ - if not text: - return [] - - # Escape RST emphasis patterns before parsing (e.g., "django-*" -> "django-\*") - text = escape_rst_emphasis(text) - - if self.state is None: - # No state machine available, return as paragraph - para = nodes.paragraph(text=text) - return [para] - - # Use the state machine to parse RST - container = nodes.container() - self.state.nested_parse( - StringList(text.split("\n")), - 0, - container, - ) - return list(container.children) - - -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) diff --git a/docs/_ext/sphinx_argparse_neo/utils.py b/docs/_ext/sphinx_argparse_neo/utils.py deleted file mode 100644 index 468b1961fa..0000000000 --- a/docs/_ext/sphinx_argparse_neo/utils.py +++ /dev/null @@ -1,78 +0,0 @@ -"""Text processing utilities for sphinx_argparse_neo. - -This module provides utilities for cleaning argparse output before rendering: -- strip_ansi: Remove ANSI escape codes (for when FORCE_COLOR is set) -""" - -from __future__ import annotations - -import re - -# ANSI escape code pattern - matches CSI sequences like \033[32m, \033[1;34m, etc. -_ANSI_RE = re.compile(r"\033\[[;?0-9]*[a-zA-Z]") - - -def strip_ansi(text: str) -> str: - r"""Remove ANSI escape codes from text. - - When FORCE_COLOR is set in the environment, argparse may include ANSI - escape codes in its output. This function removes them so the output - renders correctly in Sphinx documentation. - - Parameters - ---------- - text : str - Text potentially containing ANSI codes. - - Returns - ------- - str - Text with ANSI codes removed. - - Examples - -------- - >>> strip_ansi("plain text") - 'plain text' - >>> strip_ansi("\033[32mgreen\033[0m") - 'green' - >>> strip_ansi("\033[1;34mbold blue\033[0m") - 'bold blue' - """ - return _ANSI_RE.sub("", text) - - -# RST emphasis pattern: matches -* that would trigger inline emphasis errors. -# Pattern matches: non-whitespace/non-backslash char, followed by -*, NOT followed by -# another * (which would be strong emphasis **). -_RST_EMPHASIS_RE = re.compile(r"(?<=[^\s\\])-\*(?!\*)") - - -def escape_rst_emphasis(text: str) -> str: - r"""Escape asterisks that would trigger RST inline emphasis. - - RST interprets ``*text*`` as emphasis. When argparse help text contains - glob patterns like ``django-*``, the ``-*`` sequence triggers RST - "Inline emphasis start-string without end-string" warnings. - - This function escapes such asterisks to prevent RST parsing errors. - - Parameters - ---------- - text : str - Text potentially containing problematic asterisks. - - Returns - ------- - str - Text with asterisks escaped where needed. - - Examples - -------- - >>> escape_rst_emphasis('tmuxp load "my-*"') - 'tmuxp load "my-\\*"' - >>> escape_rst_emphasis("plain text") - 'plain text' - >>> escape_rst_emphasis("*emphasis* is ok") - '*emphasis* is ok' - """ - return _RST_EMPHASIS_RE.sub(r"-\*", text) diff --git a/docs/_ext/sphinx_fonts.py b/docs/_ext/sphinx_fonts.py deleted file mode 100644 index e8d2a692ae..0000000000 --- a/docs/_ext/sphinx_fonts.py +++ /dev/null @@ -1,153 +0,0 @@ -"""Sphinx extension for self-hosted fonts via Fontsource CDN. - -Downloads font files at build time, caches them locally, and passes -structured font data to the template context for inline @font-face CSS. -""" - -from __future__ import annotations - -import logging -import pathlib -import shutil -import typing as t -import urllib.error -import urllib.request - -if t.TYPE_CHECKING: - from sphinx.application import Sphinx - -logger = logging.getLogger(__name__) - -CDN_TEMPLATE = ( - "https://cdn.jsdelivr.net/npm/{package}@{version}" - "/files/{font_id}-{subset}-{weight}-{style}.woff2" -) - - -class SetupDict(t.TypedDict): - """Return type for Sphinx extension setup().""" - - version: str - parallel_read_safe: bool - parallel_write_safe: bool - - -def _cache_dir() -> pathlib.Path: - return pathlib.Path.home() / ".cache" / "sphinx-fonts" - - -def _cdn_url( - package: str, - version: str, - font_id: str, - subset: str, - weight: int, - style: str, -) -> str: - return CDN_TEMPLATE.format( - package=package, - version=version, - font_id=font_id, - subset=subset, - weight=weight, - style=style, - ) - - -def _download_font(url: str, dest: pathlib.Path) -> bool: - if dest.exists(): - logger.debug("font cached: %s", dest.name) - return True - dest.parent.mkdir(parents=True, exist_ok=True) - try: - urllib.request.urlretrieve(url, dest) - logger.info("downloaded font: %s", dest.name) - except (urllib.error.URLError, OSError): - if dest.exists(): - dest.unlink() - logger.warning("failed to download font: %s", url) - return False - return True - - -def _on_builder_inited(app: Sphinx) -> None: - if app.builder.format != "html": - return - - fonts: list[dict[str, t.Any]] = app.config.sphinx_fonts - variables: dict[str, str] = app.config.sphinx_font_css_variables - if not fonts: - return - - cache = _cache_dir() - static_dir = pathlib.Path(app.outdir) / "_static" - fonts_dir = static_dir / "fonts" - fonts_dir.mkdir(parents=True, exist_ok=True) - - font_faces: list[dict[str, str]] = [] - for font in fonts: - font_id = font["package"].split("/")[-1] - version = font["version"] - package = font["package"] - subset = font.get("subset", "latin") - for weight in font["weights"]: - for style in font["styles"]: - filename = f"{font_id}-{subset}-{weight}-{style}.woff2" - cached = cache / filename - url = _cdn_url(package, version, font_id, subset, weight, style) - if _download_font(url, cached): - shutil.copy2(cached, fonts_dir / filename) - font_faces.append( - { - "family": font["family"], - "style": style, - "weight": str(weight), - "filename": filename, - } - ) - - preload_hrefs: list[str] = [] - preload_specs: list[tuple[str, int, str]] = app.config.sphinx_font_preload - for family_name, weight, style in preload_specs: - for font in fonts: - if font["family"] == family_name: - font_id = font["package"].split("/")[-1] - subset = font.get("subset", "latin") - filename = f"{font_id}-{subset}-{weight}-{style}.woff2" - preload_hrefs.append(filename) - break - - fallbacks: list[dict[str, str]] = app.config.sphinx_font_fallbacks - - app._font_preload_hrefs = preload_hrefs # type: ignore[attr-defined] - app._font_faces = font_faces # type: ignore[attr-defined] - app._font_fallbacks = fallbacks # type: ignore[attr-defined] - app._font_css_variables = variables # type: ignore[attr-defined] - - -def _on_html_page_context( - app: Sphinx, - pagename: str, - templatename: str, - context: dict[str, t.Any], - doctree: t.Any, -) -> None: - context["font_preload_hrefs"] = getattr(app, "_font_preload_hrefs", []) - context["font_faces"] = getattr(app, "_font_faces", []) - context["font_fallbacks"] = getattr(app, "_font_fallbacks", []) - context["font_css_variables"] = getattr(app, "_font_css_variables", {}) - - -def setup(app: Sphinx) -> SetupDict: - """Register config values, events, and return extension metadata.""" - app.add_config_value("sphinx_fonts", [], "html") - app.add_config_value("sphinx_font_fallbacks", [], "html") - app.add_config_value("sphinx_font_css_variables", {}, "html") - app.add_config_value("sphinx_font_preload", [], "html") - app.connect("builder-inited", _on_builder_inited) - app.connect("html-page-context", _on_html_page_context) - return { - "version": "1.0", - "parallel_read_safe": True, - "parallel_write_safe": True, - } diff --git a/docs/_static/js/spa-nav.js b/docs/_static/js/spa-nav.js deleted file mode 100644 index cd99233fb7..0000000000 --- a/docs/_static/js/spa-nav.js +++ /dev/null @@ -1,254 +0,0 @@ -/** - * SPA-like navigation for Sphinx/Furo docs. - * - * Intercepts internal link clicks and swaps only the content that changes - * (article, sidebar nav tree, TOC drawer), preserving sidebar scroll - * position, theme state, and avoiding full-page reloads. - * - * Progressive enhancement: no-op when fetch/DOMParser/pushState unavailable. - */ -(function () { - "use strict"; - - if (!window.fetch || !window.DOMParser || !window.history?.pushState) return; - - // --- Theme toggle (replicates Furo's cycleThemeOnce) --- - - function cycleTheme() { - var current = localStorage.getItem("theme") || "auto"; - var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches; - var next; - if (current === "auto") next = prefersDark ? "light" : "dark"; - else if (current === "dark") next = prefersDark ? "auto" : "light"; - else next = prefersDark ? "dark" : "auto"; - document.body.dataset.theme = next; - localStorage.setItem("theme", next); - } - - // --- Copy button injection --- - - var copyBtnTemplate = null; - - function captureCopyIcon() { - var btn = document.querySelector(".copybtn"); - if (btn) copyBtnTemplate = btn.cloneNode(true); - } - - function addCopyButtons() { - if (!copyBtnTemplate) captureCopyIcon(); - if (!copyBtnTemplate) return; - var cells = document.querySelectorAll("div.highlight pre"); - cells.forEach(function (cell, i) { - cell.id = "codecell" + i; - var next = cell.nextElementSibling; - if (next && next.classList.contains("copybtn")) { - next.setAttribute("data-clipboard-target", "#codecell" + i); - } else { - var btn = copyBtnTemplate.cloneNode(true); - btn.setAttribute("data-clipboard-target", "#codecell" + i); - cell.insertAdjacentElement("afterend", btn); - } - }); - } - - // --- Minimal scrollspy --- - - var scrollCleanup = null; - - function initScrollSpy() { - if (scrollCleanup) scrollCleanup(); - scrollCleanup = null; - - var links = document.querySelectorAll(".toc-tree a"); - if (!links.length) return; - - var entries = []; - links.forEach(function (a) { - var id = (a.getAttribute("href") || "").split("#")[1]; - var el = id && document.getElementById(id); - var li = a.closest("li"); - if (el && li) entries.push({ el: el, li: li }); - }); - if (!entries.length) return; - - function update() { - var offset = - parseFloat(getComputedStyle(document.documentElement).fontSize) * 4; - var active = null; - for (var i = entries.length - 1; i >= 0; i--) { - if (entries[i].el.getBoundingClientRect().top <= offset) { - active = entries[i]; - break; - } - } - entries.forEach(function (e) { - e.li.classList.remove("scroll-current"); - }); - if (active) active.li.classList.add("scroll-current"); - } - - window.addEventListener("scroll", update, { passive: true }); - update(); - scrollCleanup = function () { - window.removeEventListener("scroll", update); - }; - } - - // --- Link interception --- - - function shouldIntercept(link, e) { - if (e.defaultPrevented || e.button !== 0) return false; - if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return false; - if (link.origin !== location.origin) return false; - if (link.target && link.target !== "_self") return false; - if (link.hasAttribute("download")) return false; - - var path = link.pathname; - if (!path.endsWith(".html") && !path.endsWith("/")) return false; - - var base = path.split("/").pop() || ""; - if ( - base === "search.html" || - base === "genindex.html" || - base === "py-modindex.html" - ) - return false; - - if (link.closest("#sidebar-projects")) return false; - if (link.pathname === location.pathname && link.hash) return false; - - return true; - } - - // --- DOM swap --- - - function swap(doc) { - [".article-container", ".sidebar-tree", ".toc-drawer"].forEach( - function (sel) { - var fresh = doc.querySelector(sel); - var stale = document.querySelector(sel); - if (fresh && stale) stale.replaceWith(fresh); - }, - ); - var title = doc.querySelector("title"); - if (title) document.title = title.textContent || ""; - - // Brand links and logo images live outside swapped regions. - // Their relative hrefs/srcs go stale after cross-depth navigation. - // Copy the correct values from the fetched document. - [".sidebar-brand", ".header-center a"].forEach(function (sel) { - var fresh = doc.querySelector(sel); - if (!fresh) return; - document.querySelectorAll(sel).forEach(function (el) { - el.setAttribute("href", fresh.getAttribute("href")); - }); - }); - var freshLogos = doc.querySelectorAll(".sidebar-logo"); - var staleLogos = document.querySelectorAll(".sidebar-logo"); - freshLogos.forEach(function (fresh, i) { - if (staleLogos[i]) { - staleLogos[i].setAttribute("src", fresh.getAttribute("src")); - } - }); - } - - function reinit() { - addCopyButtons(); - initScrollSpy(); - var btn = document.querySelector(".content-icon-container .theme-toggle"); - if (btn) btn.addEventListener("click", cycleTheme); - } - - // --- Navigation --- - - var currentCtrl = null; - - async function navigate(url, isPop) { - if (currentCtrl) currentCtrl.abort(); - var ctrl = new AbortController(); - currentCtrl = ctrl; - - try { - var resp = await fetch(url, { signal: ctrl.signal }); - if (!resp.ok) throw new Error(resp.status); - - var html = await resp.text(); - var doc = new DOMParser().parseFromString(html, "text/html"); - - if (!doc.querySelector(".article-container")) - throw new Error("no article"); - - var applySwap = function () { - swap(doc); - - if (!isPop) history.pushState({ spa: true }, "", url); - - if (!isPop) { - var hash = new URL(url, location.href).hash; - if (hash) { - var el = document.querySelector(hash); - if (el) el.scrollIntoView(); - } else { - window.scrollTo(0, 0); - } - } - - reinit(); - }; - - if (document.startViewTransition) { - document.startViewTransition(applySwap); - } else { - applySwap(); - } - } catch (err) { - if (err.name === "AbortError") return; - window.location.href = url; - } finally { - if (currentCtrl === ctrl) currentCtrl = null; - } - } - - // --- Events --- - - document.addEventListener("click", function (e) { - var link = e.target.closest("a[href]"); - if (link && shouldIntercept(link, e)) { - e.preventDefault(); - navigate(link.href, false); - } - }); - - history.replaceState({ spa: true }, ""); - - window.addEventListener("popstate", function () { - navigate(location.href, true); - }); - - // --- Hover prefetch --- - - var prefetchTimer = null; - - document.addEventListener("mouseover", function (e) { - var link = e.target.closest("a[href]"); - if (!link || link.origin !== location.origin) return; - if (!link.pathname.endsWith(".html") && !link.pathname.endsWith("/")) - return; - - clearTimeout(prefetchTimer); - prefetchTimer = setTimeout(function () { - fetch(link.href, { priority: "low" }).catch(function () {}); - }, 65); - }); - - document.addEventListener("mouseout", function (e) { - if (e.target.closest("a[href]")) clearTimeout(prefetchTimer); - }); - - // --- Init --- - - // Copy buttons are injected by copybutton.js on DOMContentLoaded. - // This defer script runs before DOMContentLoaded, so our handler - // fires after copybutton's handler (registration order preserved). - document.addEventListener("DOMContentLoaded", captureCopyIcon); -})(); diff --git a/docs/conf.py b/docs/conf.py index 3d77fc8993..208f183724 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,19 +1,9 @@ -# flake8: NOQA: E501 """Sphinx documentation configuration for tmuxp.""" from __future__ import annotations -import contextlib -import inspect import pathlib import sys -import typing as t -from os.path import relpath - -import tmuxp - -if t.TYPE_CHECKING: - from sphinx.application import Sphinx # Get the project root dir, which is the parent dir of this cwd = pathlib.Path(__file__).parent @@ -21,272 +11,38 @@ src_root = project_root / "src" sys.path.insert(0, str(src_root)) -sys.path.insert(0, str(cwd / "_ext")) +sys.path.insert(0, str(cwd / "_ext")) # for local aafig extension # package data about: dict[str, str] = {} with (src_root / "tmuxp" / "__about__.py").open() as fp: exec(fp.read(), about) -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.intersphinx", - "sphinx_autodoc_typehints", - "sphinx.ext.todo", - "sphinx.ext.napoleon", - "sphinx.ext.linkcode", - "aafig", - "sphinx_fonts", - "argparse_exemplar", # Custom sphinx-argparse replacement - "sphinx_inline_tabs", - "sphinx_copybutton", - "sphinxext.opengraph", - "sphinxext.rediraffe", - "myst_parser", - "linkify_issues", - "sphinx_design", -] - -myst_enable_extensions = [ - "colon_fence", - "substitution", - "replacements", - "strikethrough", - "linkify", -] - -myst_heading_anchors = 4 - -templates_path = ["_templates"] - -source_suffix = {".rst": "restructuredtext", ".md": "markdown"} - -master_doc = "index" - -project = about["__title__"] -project_copyright = about["__copyright__"] - -version = "{}".format(".".join(about["__version__"].split("."))[:2]) -release = "{}".format(about["__version__"]) - -exclude_patterns = ["_build"] - -pygments_style = "monokai" -pygments_dark_style = "monokai" - -html_css_files = ["css/custom.css", "css/argparse-highlight.css"] -html_extra_path = ["manifest.json"] -html_static_path = ["_static"] -html_favicon = "_static/favicon.ico" -html_theme = "furo" -html_theme_path: list[str] = [] -html_theme_options: dict[str, str | list[dict[str, str]]] = { - "light_logo": "img/tmuxp.svg", - "dark_logo": "img/tmuxp.svg", - "footer_icons": [ - { - "name": "GitHub", - "url": about["__github__"], - "html": """ - - - - """, - "class": "", - }, - ], - "source_repository": f"{about['__github__']}/", - "source_branch": "master", - "source_directory": "docs/", -} -html_sidebars = { - "**": [ - "sidebar/scroll-start.html", - "sidebar/brand.html", - "sidebar/search.html", - "sidebar/navigation.html", - "sidebar/projects.html", - "sidebar/scroll-end.html", - ], -} - -# linkify_issues -issue_url_tpl = about["__github__"] + "/issues/{issue_id}" - -# sphinx.ext.autodoc -toc_object_entries_show_parents = "hide" -autodoc_default_options = { - "undoc-members": True, - "members": True, - "private-members": True, - "show-inheritance": True, - "member-order": "bysource", -} - -# sphinx-autodoc-typehints -# Suppress warnings for forward references that can't be resolved -# (types in TYPE_CHECKING blocks used for circular import avoidance) -suppress_warnings = [ - "sphinx_autodoc_typehints.forward_reference", -] - -# sphinxext.opengraph -ogp_site_url = about["__docs__"] -ogp_image = "_static/img/icons/icon-192x192.png" -ogp_site_name = about["__title__"] - -# sphinx-copybutton -copybutton_prompt_text = ( - r">>> |\.\.\. |> |\$ |\# | In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " -) -copybutton_prompt_is_regexp = True -copybutton_remove_prompts = True -copybutton_line_continuation_character = "\\" - -# sphinxext-rediraffe -rediraffe_redirects = "redirects.txt" -rediraffe_branch = "master~1" - -# aafig format, try to get working with pdf -aafig_format = {"latex": "pdf", "html": "gif"} -aafig_default_options = {"scale": 0.75, "aspect": 0.5, "proportional": True} - -# sphinx_fonts — self-hosted IBM Plex via Fontsource CDN -sphinx_fonts = [ - { - "family": "IBM Plex Sans", - "package": "@fontsource/ibm-plex-sans", - "version": "5.2.8", - "weights": [400, 500, 600, 700], - "styles": ["normal", "italic"], - "subset": "latin", +from gp_sphinx.config import make_linkcode_resolve, merge_sphinx_config # noqa: E402 + +import tmuxp # noqa: E402 + +conf = merge_sphinx_config( + project=about["__title__"], + version=about["__version__"], + copyright=about["__copyright__"], + source_repository=f"{about['__github__']}/", + docs_url=about["__docs__"], + source_branch="master", + light_logo="img/tmuxp.svg", + dark_logo="img/tmuxp.svg", + extra_extensions=["aafig", "sphinx_argparse_neo.exemplar"], + intersphinx_mapping={ + "python": ("https://docs.python.org/", None), + "libtmux": ("https://libtmux.git-pull.com/", None), }, - { - "family": "IBM Plex Mono", - "package": "@fontsource/ibm-plex-mono", - "version": "5.2.7", - "weights": [400], - "styles": ["normal", "italic"], - "subset": "latin", - }, -] - -sphinx_font_preload = [ - ("IBM Plex Sans", 400, "normal"), # body text - ("IBM Plex Sans", 700, "normal"), # headings - ("IBM Plex Mono", 400, "normal"), # code blocks -] - -sphinx_font_fallbacks = [ - { - "family": "IBM Plex Sans Fallback", - "src": 'local("Arial"), local("Helvetica Neue"), local("Helvetica")', - "size_adjust": "110.6%", - "ascent_override": "92.7%", - "descent_override": "24.9%", - "line_gap_override": "0%", - }, - { - "family": "IBM Plex Mono Fallback", - "src": 'local("Courier New"), local("Courier")', - "size_adjust": "100%", - "ascent_override": "102.5%", - "descent_override": "27.5%", - "line_gap_override": "0%", - }, -] - -sphinx_font_css_variables = { - "--font-stack": '"IBM Plex Sans", "IBM Plex Sans Fallback", -apple-system, BlinkMacSystemFont, sans-serif', - "--font-stack--monospace": '"IBM Plex Mono", "IBM Plex Mono Fallback", SFMono-Regular, Menlo, Consolas, monospace', - "--font-stack--headings": "var(--font-stack)", -} - -intersphinx_mapping = { - "python": ("https://docs.python.org/", None), - "libtmux": ("https://libtmux.git-pull.com/", None), -} - - -def linkcode_resolve(domain: str, info: dict[str, str]) -> None | str: - """ - Determine the URL corresponding to Python object. - - Notes - ----- - From https://github.com/numpy/numpy/blob/v1.15.1/doc/source/conf.py, 7c49cfa - on Jul 31. License BSD-3. https://github.com/numpy/numpy/blob/v1.15.1/LICENSE.txt - """ - if domain != "py": - return None - - modname = info["module"] - fullname = info["fullname"] - - submod = sys.modules.get(modname) - if submod is None: - return None - - obj = submod - for part in fullname.split("."): - try: - obj = getattr(obj, part) - except Exception: # NOQA: PERF203 - return None - - # strip decorators, which would resolve to the source of the decorator - # possibly an upstream bug in getsourcefile, bpo-1764286 - try: - unwrap = inspect.unwrap - except AttributeError: - pass - else: - if callable(obj): - obj = unwrap(obj) - - try: - fn = inspect.getsourcefile(obj) - except Exception: - fn = None - if not fn: - return None - - try: - source, lineno = inspect.getsourcelines(obj) - except Exception: - lineno = None - - linespec = f"#L{lineno}-L{lineno + len(source) - 1}" if lineno else "" - - fn = relpath(fn, start=pathlib.Path(tmuxp.__file__).parent) - - if "dev" in about["__version__"]: - return "{}/blob/master/{}/{}/{}{}".format( - about["__github__"], - "src", - about["__package_name__"], - fn, - linespec, - ) - return "{}/blob/v{}/{}/{}/{}{}".format( - about["__github__"], - about["__version__"], - "src", - about["__package_name__"], - fn, - linespec, - ) - - -def remove_tabs_js(app: Sphinx, exc: Exception) -> None: - """Fix for sphinx-inline-tabs#18.""" - if app.builder.format == "html" and not exc: - tabs_js = pathlib.Path(app.builder.outdir) / "_static" / "tabs.js" - with contextlib.suppress(FileNotFoundError): - tabs_js.unlink() # When python 3.7 deprecated, use missing_ok=True - - -def setup(app: Sphinx) -> None: - """Sphinx setup hook.""" - app.add_js_file("js/spa-nav.js", loading_method="defer") - app.connect("build-finished", remove_tabs_js) + linkcode_resolve=make_linkcode_resolve(tmuxp, about["__github__"]), + # tmuxp-specific overrides + html_css_files=["css/custom.css"], + html_extra_path=["manifest.json"], + html_favicon="_static/favicon.ico", + aafig_format={"latex": "pdf", "html": "gif"}, + aafig_default_options={"scale": 0.75, "aspect": 0.5, "proportional": True}, + rediraffe_redirects="redirects.txt", +) +globals().update(conf) diff --git a/pyproject.toml b/pyproject.toml index 02fc0e28f6..2154eebc2e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,18 +57,10 @@ dev = [ # Docs "aafigure", # https://launchpad.net/aafigure "pillow", # https://pillow.readthedocs.io/ - "sphinx<9", # https://www.sphinx-doc.org/ - "furo", # https://pradyunsg.me/furo/ + "gp-sphinx", # https://gp-sphinx.git-pull.com/ + "sphinx-argparse-neo", # https://gp-sphinx.git-pull.com/ "gp-libs", # https://gp-libs.git-pull.com/ "sphinx-autobuild", # https://sphinx-extensions.readthedocs.io/en/latest/sphinx-autobuild.html - "sphinx-autodoc-typehints", # https://sphinx-autodoc-typehints.readthedocs.io/ - "sphinx-inline-tabs", # https://sphinx-inline-tabs.readthedocs.io/ - "sphinxext-opengraph", # https://sphinxext-opengraph.readthedocs.io/ - "sphinx-copybutton", # https://sphinx-copybutton.readthedocs.io/ - "sphinxext-rediraffe", # https://sphinxext-rediraffe.readthedocs.io/ - "sphinx-design", # https://sphinx-design.readthedocs.io/ - "myst-parser", # https://myst-parser.readthedocs.io/ - "linkify-it-py", # https://github.com/tsutsu3/linkify-it-py # Testing "gp-libs", "pytest", @@ -90,18 +82,10 @@ dev = [ docs = [ "aafigure", # https://launchpad.net/aafigure "pillow", # https://pillow.readthedocs.io/ - "sphinx<9", # https://www.sphinx-doc.org/ - "furo", # https://pradyunsg.me/furo/ + "gp-sphinx", # https://gp-sphinx.git-pull.com/ + "sphinx-argparse-neo", # https://gp-sphinx.git-pull.com/ "gp-libs", # https://gp-libs.git-pull.com/ "sphinx-autobuild", # https://sphinx-extensions.readthedocs.io/en/latest/sphinx-autobuild.html - "sphinx-autodoc-typehints", # https://sphinx-autodoc-typehints.readthedocs.io/ - "sphinx-inline-tabs", # https://sphinx-inline-tabs.readthedocs.io/ - "sphinxext-opengraph", # https://sphinxext-opengraph.readthedocs.io/ - "sphinx-copybutton", # https://sphinx-copybutton.readthedocs.io/ - "sphinxext-rediraffe", # https://sphinxext-rediraffe.readthedocs.io/ - "sphinx-design", # https://sphinx-design.readthedocs.io/ - "myst-parser", # https://myst-parser.readthedocs.io/ - "linkify-it-py", # https://github.com/tsutsu3/linkify-it-py ] testing = [ "gp-libs", @@ -123,6 +107,12 @@ lint = [ "types-PyYAML", ] +[tool.uv.sources] +gp-sphinx = { path = "../gp-sphinx/packages/gp-sphinx", editable = true } +sphinx-fonts = { path = "../gp-sphinx/packages/sphinx-fonts", editable = true } +sphinx-gptheme = { path = "../gp-sphinx/packages/sphinx-gptheme", editable = true } +sphinx-argparse-neo = { path = "../gp-sphinx/packages/sphinx-argparse-neo", editable = true } + [build-system] requires = ["hatchling"] build-backend = "hatchling.build" @@ -176,9 +166,6 @@ module = [ "sphinx_argparse_neo", "sphinx_argparse_neo.*", "sphinx_fonts", - "cli_usage_lexer", - "argparse_lexer", - "argparse_roles", "docutils", "docutils.*", "pygments", diff --git a/tests/docs/_ext/conftest.py b/tests/docs/_ext/conftest.py index fa2919bdcf..3124d5b7b7 100644 --- a/tests/docs/_ext/conftest.py +++ b/tests/docs/_ext/conftest.py @@ -1,11 +1,3 @@ """Fixtures and configuration for docs extension tests.""" from __future__ import annotations - -import pathlib -import sys - -# Add docs/_ext to path so we can import the extension module -docs_ext_path = pathlib.Path(__file__).parent.parent.parent.parent / "docs" / "_ext" -if str(docs_ext_path) not in sys.path: - sys.path.insert(0, str(docs_ext_path)) diff --git a/tests/docs/_ext/test_argparse_exemplar.py b/tests/docs/_ext/test_argparse_exemplar.py index 18679827d5..c25b48f9da 100644 --- a/tests/docs/_ext/test_argparse_exemplar.py +++ b/tests/docs/_ext/test_argparse_exemplar.py @@ -13,7 +13,8 @@ import typing as t import pytest -from argparse_exemplar import ( # type: ignore[import-not-found] +from docutils import nodes +from sphinx_argparse_neo.exemplar import ( ExemplarConfig, _extract_sections_from_container, _is_examples_section, @@ -26,7 +27,6 @@ process_node, transform_definition_list, ) -from docutils import nodes # --- is_examples_term tests --- diff --git a/tests/docs/_ext/test_argparse_lexer.py b/tests/docs/_ext/test_argparse_lexer.py index 7a621f1093..d5966007a8 100644 --- a/tests/docs/_ext/test_argparse_lexer.py +++ b/tests/docs/_ext/test_argparse_lexer.py @@ -5,7 +5,7 @@ import typing as t import pytest -from argparse_lexer import ( +from sphinx_argparse_neo.lexer import ( ArgparseHelpLexer, ArgparseLexer, ArgparseUsageLexer, diff --git a/tests/docs/_ext/test_argparse_roles.py b/tests/docs/_ext/test_argparse_roles.py index c31e12691a..08093c2481 100644 --- a/tests/docs/_ext/test_argparse_roles.py +++ b/tests/docs/_ext/test_argparse_roles.py @@ -5,7 +5,8 @@ import typing as t import pytest -from argparse_roles import ( +from docutils import nodes +from sphinx_argparse_neo.roles import ( cli_choice_role, cli_command_role, cli_default_role, @@ -14,7 +15,6 @@ normalize_options, register_roles, ) -from docutils import nodes # --- normalize_options tests --- diff --git a/tests/docs/_ext/test_cli_usage_lexer.py b/tests/docs/_ext/test_cli_usage_lexer.py index 3c32ebac6d..fab92a3d14 100644 --- a/tests/docs/_ext/test_cli_usage_lexer.py +++ b/tests/docs/_ext/test_cli_usage_lexer.py @@ -5,7 +5,7 @@ import typing as t import pytest -from cli_usage_lexer import ( +from sphinx_argparse_neo.cli_usage_lexer import ( CLIUsageLexer, tokenize_usage, ) diff --git a/tests/docs/_ext/test_sphinx_fonts.py b/tests/docs/_ext/test_sphinx_fonts.py index 22f546a2e1..300958ab2c 100644 --- a/tests/docs/_ext/test_sphinx_fonts.py +++ b/tests/docs/_ext/test_sphinx_fonts.py @@ -494,7 +494,7 @@ def test_setup_return_value() -> None: result = sphinx_fonts.setup(app) assert result == { - "version": "1.0", + "version": sphinx_fonts.__version__, "parallel_read_safe": True, "parallel_write_safe": True, } diff --git a/uv.lock b/uv.lock index 90e0fc9b54..36a3bce83d 100644 --- a/uv.lock +++ b/uv.lock @@ -391,6 +391,49 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/18/f9/5d78d1dda9cb0f27d6f2305e95a58edbff935a62d53ec3227a3518cb4f72/gp_libs-0.0.17-py3-none-any.whl", hash = "sha256:7ce96d5e09980c0dc82062ab3e3b911600bd44da97a64fb78379f1af9a79d4d3", size = 16157, upload-time = "2025-12-07T22:44:48.036Z" }, ] +[[package]] +name = "gp-sphinx" +version = "0.0.1a0" +source = { editable = "../gp-sphinx/packages/gp-sphinx" } +dependencies = [ + { name = "docutils" }, + { name = "gp-libs" }, + { name = "linkify-it-py" }, + { name = "myst-parser", version = "4.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "myst-parser", version = "5.0.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-autodoc-typehints", version = "3.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx-autodoc-typehints", version = "3.5.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-copybutton" }, + { name = "sphinx-design", version = "0.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx-design", version = "0.7.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-fonts" }, + { name = "sphinx-gptheme" }, + { name = "sphinx-inline-tabs" }, + { name = "sphinxext-opengraph" }, + { name = "sphinxext-rediraffe" }, +] + +[package.metadata] +requires-dist = [ + { name = "docutils" }, + { name = "gp-libs" }, + { name = "linkify-it-py" }, + { name = "myst-parser" }, + { name = "sphinx", specifier = "<9" }, + { name = "sphinx-argparse-neo", marker = "extra == 'argparse'", editable = "../gp-sphinx/packages/sphinx-argparse-neo" }, + { name = "sphinx-autodoc-typehints" }, + { name = "sphinx-copybutton" }, + { name = "sphinx-design" }, + { name = "sphinx-fonts", editable = "../gp-sphinx/packages/sphinx-fonts" }, + { name = "sphinx-gptheme", editable = "../gp-sphinx/packages/sphinx-gptheme" }, + { name = "sphinx-inline-tabs" }, + { name = "sphinxext-opengraph" }, + { name = "sphinxext-rediraffe" }, +] +provides-extras = ["argparse"] + [[package]] name = "h11" version = "0.16.0" @@ -1189,6 +1232,24 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/31/53/136e9eca6e0b9dc0e1962e2c908fbea2e5ac000c2a2fbd9a35797958c48b/sphinx-8.2.3-py3-none-any.whl", hash = "sha256:4405915165f13521d875a8c29c8970800a0141c14cc5416a38feca4ea5d9b9c3", size = 3589741, upload-time = "2025-03-02T22:31:56.836Z" }, ] +[[package]] +name = "sphinx-argparse-neo" +version = "0.0.1a0" +source = { editable = "../gp-sphinx/packages/sphinx-argparse-neo" } +dependencies = [ + { name = "docutils" }, + { name = "pygments" }, + { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, +] + +[package.metadata] +requires-dist = [ + { name = "docutils" }, + { name = "pygments" }, + { name = "sphinx" }, +] + [[package]] name = "sphinx-autobuild" version = "2024.10.3" @@ -1318,6 +1379,29 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/30/cf/45dd359f6ca0c3762ce0490f681da242f0530c49c81050c035c016bfdd3a/sphinx_design-0.7.0-py3-none-any.whl", hash = "sha256:f82bf179951d58f55dca78ab3706aeafa496b741a91b1911d371441127d64282", size = 2220350, upload-time = "2026-01-19T13:12:51.077Z" }, ] +[[package]] +name = "sphinx-fonts" +version = "0.0.1a0" +source = { editable = "../gp-sphinx/packages/sphinx-fonts" } +dependencies = [ + { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, + { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, +] + +[package.metadata] +requires-dist = [{ name = "sphinx" }] + +[[package]] +name = "sphinx-gptheme" +version = "0.0.1a0" +source = { editable = "../gp-sphinx/packages/sphinx-gptheme" } +dependencies = [ + { name = "furo" }, +] + +[package.metadata] +requires-dist = [{ name = "furo" }] + [[package]] name = "sphinx-inline-tabs" version = "2025.12.21.14" @@ -1443,12 +1527,9 @@ dev = [ { name = "aafigure" }, { name = "codecov" }, { name = "coverage" }, - { name = "furo" }, { name = "gp-libs" }, - { name = "linkify-it-py" }, + { name = "gp-sphinx" }, { name = "mypy" }, - { name = "myst-parser", version = "4.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "myst-parser", version = "5.0.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, { name = "pillow" }, { name = "pytest" }, { name = "pytest-cov" }, @@ -1456,42 +1537,21 @@ dev = [ { name = "pytest-rerunfailures" }, { name = "pytest-watcher" }, { name = "ruff" }, - { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-argparse-neo" }, { name = "sphinx-autobuild", version = "2024.10.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx-autobuild", version = "2025.8.25", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, - { name = "sphinx-autodoc-typehints", version = "3.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "sphinx-autodoc-typehints", version = "3.5.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, - { name = "sphinx-copybutton" }, - { name = "sphinx-design", version = "0.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "sphinx-design", version = "0.7.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, - { name = "sphinx-inline-tabs" }, - { name = "sphinxext-opengraph" }, - { name = "sphinxext-rediraffe" }, { name = "types-docutils" }, { name = "types-pygments" }, { name = "types-pyyaml" }, ] docs = [ { name = "aafigure" }, - { name = "furo" }, { name = "gp-libs" }, - { name = "linkify-it-py" }, - { name = "myst-parser", version = "4.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "myst-parser", version = "5.0.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "gp-sphinx" }, { name = "pillow" }, - { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, + { name = "sphinx-argparse-neo" }, { name = "sphinx-autobuild", version = "2024.10.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx-autobuild", version = "2025.8.25", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, - { name = "sphinx-autodoc-typehints", version = "3.0.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "sphinx-autodoc-typehints", version = "3.5.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, - { name = "sphinx-copybutton" }, - { name = "sphinx-design", version = "0.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, - { name = "sphinx-design", version = "0.7.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, - { name = "sphinx-inline-tabs" }, - { name = "sphinxext-opengraph" }, - { name = "sphinxext-rediraffe" }, ] lint = [ { name = "mypy" }, @@ -1524,11 +1584,9 @@ dev = [ { name = "aafigure" }, { name = "codecov" }, { name = "coverage" }, - { name = "furo" }, { name = "gp-libs" }, - { name = "linkify-it-py" }, + { name = "gp-sphinx", editable = "../gp-sphinx/packages/gp-sphinx" }, { name = "mypy" }, - { name = "myst-parser" }, { name = "pillow" }, { name = "pytest" }, { name = "pytest-cov" }, @@ -1536,33 +1594,19 @@ dev = [ { name = "pytest-rerunfailures" }, { name = "pytest-watcher" }, { name = "ruff" }, - { name = "sphinx", specifier = "<9" }, + { name = "sphinx-argparse-neo", editable = "../gp-sphinx/packages/sphinx-argparse-neo" }, { name = "sphinx-autobuild" }, - { name = "sphinx-autodoc-typehints" }, - { name = "sphinx-copybutton" }, - { name = "sphinx-design" }, - { name = "sphinx-inline-tabs" }, - { name = "sphinxext-opengraph" }, - { name = "sphinxext-rediraffe" }, { name = "types-docutils" }, { name = "types-pygments" }, { name = "types-pyyaml" }, ] docs = [ { name = "aafigure" }, - { name = "furo" }, { name = "gp-libs" }, - { name = "linkify-it-py" }, - { name = "myst-parser" }, + { name = "gp-sphinx", editable = "../gp-sphinx/packages/gp-sphinx" }, { name = "pillow" }, - { name = "sphinx", specifier = "<9" }, + { name = "sphinx-argparse-neo", editable = "../gp-sphinx/packages/sphinx-argparse-neo" }, { name = "sphinx-autobuild" }, - { name = "sphinx-autodoc-typehints" }, - { name = "sphinx-copybutton" }, - { name = "sphinx-design" }, - { name = "sphinx-inline-tabs" }, - { name = "sphinxext-opengraph" }, - { name = "sphinxext-rediraffe" }, ] lint = [ { name = "mypy" }, From bf1ea88301a24507b19a4a62f9571d582764f783 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 29 Mar 2026 09:47:13 -0500 Subject: [PATCH 2/7] py(deps[gp-sphinx]): Point uv sources to git-pull/gp-sphinx#init-2 why: Switch from local editable path sources to git sources so the branch is self-contained and reviewable without a local gp-sphinx checkout. Points to the init-2 branch where the workspace packages live. what: - gp-sphinx, sphinx-fonts, sphinx-gptheme, sphinx-argparse-neo: change from path+editable to git+branch+subdirectory sources --- pyproject.toml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 2154eebc2e..95d78853e1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -108,10 +108,10 @@ lint = [ ] [tool.uv.sources] -gp-sphinx = { path = "../gp-sphinx/packages/gp-sphinx", editable = true } -sphinx-fonts = { path = "../gp-sphinx/packages/sphinx-fonts", editable = true } -sphinx-gptheme = { path = "../gp-sphinx/packages/sphinx-gptheme", editable = true } -sphinx-argparse-neo = { path = "../gp-sphinx/packages/sphinx-argparse-neo", editable = true } +gp-sphinx = { git = "https://github.com/git-pull/gp-sphinx", branch = "init-2", subdirectory = "packages/gp-sphinx" } +sphinx-fonts = { git = "https://github.com/git-pull/gp-sphinx", branch = "init-2", subdirectory = "packages/sphinx-fonts" } +sphinx-gptheme = { git = "https://github.com/git-pull/gp-sphinx", branch = "init-2", subdirectory = "packages/sphinx-gptheme" } +sphinx-argparse-neo = { git = "https://github.com/git-pull/gp-sphinx", branch = "init-2", subdirectory = "packages/sphinx-argparse-neo" } [build-system] requires = ["hatchling"] From 10ab4561b909353e8ccd0f867bfefc9cd235f9e4 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 29 Mar 2026 10:15:47 -0500 Subject: [PATCH 3/7] docs(chore): Remove files now provided by sphinx-gptheme MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit why: All removed files are now bundled in sphinx-gptheme and loaded automatically, making local copies pure maintenance debt. what: - Delete argparse-highlight.css — identical to theme bundled version - Delete custom.css — replaced by tmuxp.css (12-line project-specific aspect-ratio overrides only; all generic CSS now from theme) - Delete _templates/page.html — identical to theme version; mask-icon moved to theme_options.mask_icon instead of hardcoded in template - Delete _templates/sidebar/brand.html — identical to theme version - Delete _templates/sidebar/projects.html — identical to theme version - Add docs/_static/css/tmuxp.css with only tmuxp-specific image aspect-ratio rules (tmuxp-demo, tmuxp-shell, tmuxp-dev-screenshot) - Update conf.py: css/custom.css → css/tmuxp.css, add theme_options={"mask_icon": "/_static/img/tmuxp.svg"} - Update uv.lock to gp-sphinx init-2 commit c2fe249 (theme: move mask-icon outside show_meta_app_icon_tags guard) --- docs/_static/css/argparse-highlight.css | 437 ------------------------ docs/_static/css/custom.css | 246 ------------- docs/_static/css/tmuxp.css | 12 + docs/_templates/page.html | 76 ----- docs/_templates/sidebar/brand.html | 18 - docs/_templates/sidebar/projects.html | 84 ----- docs/conf.py | 3 +- uv.lock | 48 +-- 8 files changed, 22 insertions(+), 902 deletions(-) delete mode 100644 docs/_static/css/argparse-highlight.css delete mode 100644 docs/_static/css/custom.css create mode 100644 docs/_static/css/tmuxp.css delete mode 100644 docs/_templates/page.html delete mode 100644 docs/_templates/sidebar/brand.html delete mode 100644 docs/_templates/sidebar/projects.html diff --git a/docs/_static/css/argparse-highlight.css b/docs/_static/css/argparse-highlight.css deleted file mode 100644 index f232c71c8c..0000000000 --- a/docs/_static/css/argparse-highlight.css +++ /dev/null @@ -1,437 +0,0 @@ -/* - * Argparse/CLI Highlighting Styles - * - * Styles for CLI inline roles and argparse help output highlighting. - * Uses "One Dark" inspired color palette (Python 3.14 argparse style). - * - * Color Palette: - * Background: #282C34 - * Default text: #CCCED4 - * Usage label: #61AFEF (blue, bold) - * Program name: #C678DD (purple, bold) - * Subcommands: #98C379 (green) - * Options: #56B6C2 (teal) - * Metavars: #E5C07B (yellow, italic) - * Choices: #98C379 (green) - * Headings: #E5E5E5 (bright, bold) - * Punctuation: #CCCED4 - */ - -/* ========================================================================== - Inline Role Styles - ========================================================================== */ - -/* - * Shared monospace font and code font-size for all CLI inline roles - */ -.cli-option, -.cli-metavar, -.cli-command, -.cli-default, -.cli-choice { - font-family: var(--font-stack--monospace); - font-size: var(--code-font-size); -} - -/* - * CLI Options - * - * Long options (--verbose) and short options (-h) both use teal color. - */ -.cli-option-long, -.cli-option-short { - color: #56b6c2; -} - -/* - * CLI Metavars - * - * Placeholder values like FILE, PATH, DIRECTORY. - * Yellow/amber to indicate "replace me" - distinct from flags (teal). - */ -.cli-metavar { - color: #e5c07b; - font-style: italic; -} - -/* - * CLI Commands and Choices - * - * Both use green to indicate valid enumerated values. - * Commands: subcommand names like sync, add, list - * Choices: enumeration values like json, yaml, table - */ -.cli-command, -.cli-choice { - color: #98c379; -} - -.cli-command { - font-weight: bold; -} - -/* - * CLI Default Values - * - * Default values shown in help text like None, "auto". - * Subtle styling to not distract from options. - */ -.cli-default { - color: #ccced4; - font-style: italic; -} - -/* ========================================================================== - Argparse Code Block Highlighting - ========================================================================== */ - -/* - * These styles apply within Pygments-highlighted code blocks using the - * argparse, argparse-usage, or argparse-help lexers. - */ - -/* Usage heading "usage:" - bold blue */ -.highlight-argparse .gh, -.highlight-argparse-usage .gh, -.highlight-argparse-help .gh { - color: #61afef; - font-weight: bold; -} - -/* Section headers like "positional arguments:", "options:" - neutral bright */ -.highlight-argparse .gs, -.highlight-argparse-help .gs { - color: #e5e5e5; - font-weight: bold; -} - -/* Long options --foo - teal */ -.highlight-argparse .nt, -.highlight-argparse-usage .nt, -.highlight-argparse-help .nt { - color: #56b6c2; - font-weight: normal; -} - -/* Short options -h - teal (same as long) */ -.highlight-argparse .na, -.highlight-argparse-usage .na, -.highlight-argparse-help .na { - color: #56b6c2; - font-weight: normal; -} - -/* Metavar placeholders FILE, PATH - yellow/amber italic */ -.highlight-argparse .nv, -.highlight-argparse-usage .nv, -.highlight-argparse-help .nv { - color: #e5c07b; - font-style: italic; -} - -/* Command/program names - purple bold */ -.highlight-argparse .nl, -.highlight-argparse-usage .nl, -.highlight-argparse-help .nl { - color: #c678dd; - font-weight: bold; -} - -/* Subcommands - bold green */ -.highlight-argparse .nf, -.highlight-argparse-usage .nf, -.highlight-argparse-help .nf { - color: #98c379; - font-weight: bold; -} - -/* Choice values - green */ -.highlight-argparse .no, -.highlight-argparse-usage .no, -.highlight-argparse-help .no, -.highlight-argparse .nc, -.highlight-argparse-usage .nc, -.highlight-argparse-help .nc { - color: #98c379; -} - -/* Punctuation [], {}, () - neutral gray */ -.highlight-argparse .p, -.highlight-argparse-usage .p, -.highlight-argparse-help .p { - color: #ccced4; -} - -/* Operators like | - neutral gray */ -.highlight-argparse .o, -.highlight-argparse-usage .o, -.highlight-argparse-help .o { - color: #ccced4; - font-weight: normal; -} - -/* ========================================================================== - Argparse Directive Highlighting (.. argparse:: output) - ========================================================================== */ - -/* - * These styles apply to the argparse directive output which uses custom - * nodes rendered by sphinx_argparse_neo. The directive adds highlight spans - * directly to the HTML output. - */ - -/* - * Usage Block (.argparse-usage) - * - * The usage block now has both .argparse-usage and .highlight-argparse-usage - * classes. The .highlight-argparse-usage selectors above already handle the - * token highlighting. These selectors provide fallback and ensure consistent - * styling. - */ - -/* Usage block container - match Pygments monokai background and code block styling */ -pre.argparse-usage { - background: var(--argparse-code-background); - font-size: var(--code-font-size); - padding: 0.625rem 0.875rem; - line-height: 1.5; - border-radius: 0.2rem; - scrollbar-color: var(--color-foreground-border) transparent; - scrollbar-width: thin; -} - -.argparse-usage .gh { - color: #61afef; - font-weight: bold; -} - -.argparse-usage .nt { - color: #56b6c2; - font-weight: normal; -} - -.argparse-usage .na { - color: #56b6c2; - font-weight: normal; -} - -.argparse-usage .nv { - color: #e5c07b; - font-style: italic; -} - -.argparse-usage .nl { - color: #c678dd; - font-weight: bold; -} - -.argparse-usage .nf { - color: #98c379; - font-weight: bold; -} - -.argparse-usage .no, -.argparse-usage .nc { - color: #98c379; -} - -.argparse-usage .o { - color: #ccced4; - font-weight: normal; -} - -.argparse-usage .p { - color: #ccced4; -} - -/* - * Argument Name (
) - * - * The argument names in the dl/dt structure are highlighted with - * semantic spans for options and metavars. - */ -.argparse-argument-name .nt { - color: #56b6c2; - font-weight: normal; -} - -.argparse-argument-name .na { - color: #56b6c2; - font-weight: normal; -} - -.argparse-argument-name .nv { - color: #e5c07b; - font-style: italic; -} - -.argparse-argument-name .nl { - color: #c678dd; - font-weight: bold; -} - -/* ========================================================================== - Argument Wrapper and Linking Styles - ========================================================================== */ - -/* - * Argparse-specific code background (monokai #272822) - * Uses a custom variable to avoid affecting Furo's --color-inline-code-background. - */ -:root { - --argparse-code-background: #272822; -} - -/* - * Background styling for argument names - subtle background like code.literal - * This provides visual weight and hierarchy for argument definitions. - */ -.argparse-argument-name { - background: var(--argparse-code-background); - border-radius: 0.2rem; - padding: 0.485rem 0.875rem; - font-family: var(--font-stack--monospace); - font-size: var(--code-font-size); - width: fit-content; - position: relative; -} - -/* - * Wrapper for linking - enables scroll-margin for fixed header navigation - * and :target pseudo-class for highlighting when linked. - */ -.argparse-argument-wrapper { - scroll-margin-top: 2.5rem; -} - -/* - * Headerlink anchor (¶) - hidden until hover - * Positioned outside the dt element to the right. - * Follows Sphinx documentation convention for linkable headings. - */ -.argparse-argument-name .headerlink { - visibility: hidden; - position: absolute; - right: -1.5rem; - top: 50%; - transform: translateY(-50%); - color: var(--color-foreground-secondary); - text-decoration: none; -} - -/* - * Show headerlink on hover or when targeted via URL fragment - */ -.argparse-argument-wrapper:hover .headerlink, -.argparse-argument-wrapper:target .headerlink { - visibility: visible; -} - -.argparse-argument-name .headerlink:hover:not(:visited) { - color: var(--color-foreground-primary); -} - -/* - * Light mode headerlink color overrides - * Needed because code block has dark background regardless of theme - */ -body[data-theme="light"] .argparse-argument-name .headerlink { - color: #9ca0a5; - - &:hover:not(:visited) { - color: #cfd0d0; - } -} - -@media (prefers-color-scheme: light) { - body:not([data-theme="dark"]) .argparse-argument-name .headerlink { - color: #9ca0a5; - - &:hover:not(:visited) { - color: #cfd0d0; - } - } -} - -/* - * Highlight when targeted via URL fragment - * Uses Furo's highlight-on-target color for consistency. - */ -.argparse-argument-wrapper:target .argparse-argument-name { - background-color: var(--color-highlight-on-target); -} - -/* - * Argument metadata definition list - * - * Renders metadata (Default, Type, Choices, Required) as a horizontal - * flexbox of key-value pairs and standalone tags. - */ -.argparse-argument-meta { - margin: 0.5rem 0 0 0; - padding: 0; - display: flex; - flex-wrap: wrap; - gap: 0.5rem 1rem; - align-items: center; -} - -.argparse-meta-item { - display: flex; - align-items: center; - gap: 0.25rem; -} - -.argparse-meta-key { - color: var(--color-foreground-secondary, #6c757d); - font-size: var(--code-font-size); -} - -.argparse-meta-key::after { - content: ":"; -} - -.argparse-meta-value .nv { - background: var(--argparse-code-background); - border-radius: 0.2rem; - padding: 0.1rem 0.3rem; - font-family: var(--font-stack--monospace); - font-size: var(--code-font-size); - color: #e5c07b; -} - -/* - * Meta tag (e.g., "Required") - follows Furo's guilabel pattern - * Uses semi-transparent amber background with border for visibility - * without the harshness of solid fills. Amber conveys "needs attention". - */ -.argparse-meta-tag { - background-color: #fef3c780; - border: 1px solid #fcd34d80; - color: var(--color-foreground-primary); - font-size: var(--code-font-size); - padding: 0.1rem 0.4rem; - border-radius: 0.2rem; - font-weight: 500; -} - -/* Dark mode: darker amber with adjusted border */ -body[data-theme="dark"] .argparse-meta-tag { - background-color: #78350f60; - border-color: #b4530980; -} - -@media (prefers-color-scheme: dark) { - body:not([data-theme="light"]) .argparse-meta-tag { - background-color: #78350f60; - border-color: #b4530980; - } -} - -/* - * Help text description - * Adds spacing above for visual separation from argument name. - */ -.argparse-argument-help { - padding-block-start: 0.5rem; -} diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css deleted file mode 100644 index ed6640c746..0000000000 --- a/docs/_static/css/custom.css +++ /dev/null @@ -1,246 +0,0 @@ -.sidebar-tree p.indented-block { - padding: var(--sidebar-item-spacing-vertical) - var(--sidebar-item-spacing-horizontal) 0 - var(--sidebar-item-spacing-horizontal); - margin-bottom: 0; -} - -.sidebar-tree p.indented-block span.indent { - margin-left: var(--sidebar-item-spacing-horizontal); - display: block; -} - -.sidebar-tree p.indented-block .project-name { - font-size: var(--sidebar-item-font-size); - font-weight: bold; - margin-right: calc(var(--sidebar-item-spacing-horizontal) / 2.5); -} - -#sidebar-projects:not(.ready) { - visibility: hidden; -} - -.sidebar-tree .active { - font-weight: bold; -} - -/* ── Global heading refinements ───────────────────────────── - * Biome-inspired scale: medium weight (500) throughout — size - * and spacing carry hierarchy, not boldness. H4-H6 add eyebrow - * treatment (uppercase, muted). `article` prefix overrides - * Furo's bare h1-h6 selectors. - * ────────────────────────────────────────────────────────── */ -article h1 { - font-size: 1.8em; - font-weight: 500; - margin-top: 1.5rem; - margin-bottom: 0.75rem; -} - -article h2 { - font-size: 1.6em; - font-weight: 500; - margin-top: 2.5rem; - margin-bottom: 0.5rem; -} - -article h3 { - font-size: 1.15em; - font-weight: 500; - margin-top: 1.5rem; - margin-bottom: 0.375rem; -} - -article h4 { - font-size: 0.85em; - font-weight: 500; - text-transform: uppercase; - letter-spacing: 0.05em; - color: var(--color-foreground-secondary); - margin-top: 1rem; - margin-bottom: 0.25rem; -} - -article h5 { - font-size: 0.8em; - font-weight: 500; - text-transform: uppercase; - letter-spacing: 0.05em; - color: var(--color-foreground-secondary); -} - -article h6 { - font-size: 0.75em; - font-weight: 500; - text-transform: uppercase; - letter-spacing: 0.05em; - color: var(--color-foreground-secondary); -} - -/* ── Changelog heading extras ─────────────────────────────── - * Vertical spacing separates consecutive version entries. - * Category headings (h3) are muted. Item headings (h4) are - * subtle. Targets #history section from CHANGES markdown. - * ────────────────────────────────────────────────────────── */ - -/* Spacing between consecutive version entries */ -#history > section + section { - margin-top: 2.5rem; -} - -/* Category headings — muted secondary color */ -#history h3 { - color: var(--color-foreground-secondary); - margin-top: 1.25rem; -} - -/* Item headings — subtle, same size as body */ -#history h4 { - font-size: 1em; - margin-top: 1rem; - text-transform: none; - letter-spacing: normal; - color: inherit; -} - -/* ── Right-panel TOC refinements ──────────────────────────── - * Adjust Furo's table-of-contents proportions for better - * readability. Inspired by Starlight defaults (Biome docs). - * Uses Furo CSS variable overrides where possible. - * ────────────────────────────────────────────────────────── */ - -/* TOC font sizes: override Furo defaults (75% → 87.5%) */ -:root { - --toc-font-size: var(--font-size--small); /* 87.5% = 14px */ - --toc-title-font-size: var(--font-size--small); /* 87.5% = 14px */ -} - -/* More generous line-height for wrapped TOC entries */ -.toc-tree { - line-height: 1.4; -} - -/* ── Flexible right-panel TOC (inner-panel padding) ───────── - * Furo hardcodes .toc-drawer to width: 15em (SASS, compiled). - * min-width: 18em overrides it; long TOC entries wrap inside - * the box instead of blowing past the viewport. - * - * Padding lives on .toc-sticky (the inner panel), not on - * .toc-drawer (the outer aside). This matches Biome/Starlight - * where the aside defines dimensions and an inner wrapper - * (.right-sidebar-panel) controls content insets. The - * scrollbar sits naturally between content and viewport edge. - * - * Content area gets flex: 1 to absorb extra space on wide - * screens. At ≤82em Furo collapses the TOC to position: fixed; - * override right offset so the drawer fully hides off-screen. - * ────────────────────────────────────────────────────────── */ -.toc-drawer { - min-width: 18em; - flex-shrink: 0; - padding-right: 0; -} - -.toc-sticky { - padding-right: 1.5em; -} - -.content { - width: auto; - max-width: 46em; - flex: 1 1 46em; - padding: 0 2em; -} - -@media (max-width: 82em) { - .toc-drawer { - right: -18em; - } -} - -/* ── Body typography refinements ──────────────────────────── - * Improve paragraph readability with wider line-height and - * sharper text rendering. Furo already sets font-smoothing. - * - * IBM Plex tracks slightly wide at default spacing; -0.01em - * tightens it to feel more natural (matches tony.sh/tony.nl). - * Kerning + ligatures polish AV/To pairs and fi/fl combos. - * ────────────────────────────────────────────────────────── */ -body { - text-rendering: optimizeLegibility; - font-kerning: normal; - font-variant-ligatures: common-ligatures; - letter-spacing: -0.01em; -} - -/* ── Code block text rendering ──────────────────────────── - * Monospace needs fixed-width columns: disable kerning, - * ligatures, and letter-spacing that body sets for prose. - * optimizeSpeed skips heuristics that can shift the grid. - * ────────────────────────────────────────────────────────── */ -pre, -code, -kbd, -samp { - text-rendering: optimizeSpeed; - font-kerning: none; - font-variant-ligatures: none; - letter-spacing: normal; -} - -article { - line-height: 1.6; -} - -/* ── Image layout shift prevention ──────────────────────── - * Reserve space for images before they load. Furo already - * sets max-width: 100%; height: auto on img. We add - * content-visibility and badge-specific height to prevent CLS. - * ────────────────────────────────────────────────────────── */ - -img { - content-visibility: auto; -} - -/* Docutils emits :width:/:height: as inline CSS (style="width: Xpx; - * height: Ypx;") rather than HTML attributes. When Furo's - * max-width: 100% constrains width below the declared value, - * the fixed height causes distortion. height: auto + aspect-ratio - * lets the browser compute the correct height from the intrinsic - * ratio once loaded; before load, aspect-ratio reserves space - * at the intended proportion — preventing both CLS and distortion. */ -article img[loading="lazy"] { - height: auto !important; -} - -/* Per-image aspect ratios for CLS reservation before load */ -img[src*="tmuxp-demo"] { - aspect-ratio: 888 / 589; -} - -img[src*="tmuxp-shell"] { - aspect-ratio: 878 / 109; -} - -img[src*="tmuxp-dev-screenshot"] { - aspect-ratio: 1030 / 605; -} - -img[src*="shields.io"], -img[src*="badge.svg"], -img[src*="codecov.io"] { - height: 20px; - width: auto; - min-width: 60px; - border-radius: 3px; - background: var(--color-background-secondary); -} - -/* ── View Transitions (SPA navigation) ──────────────────── - * Crossfade between pages during SPA navigation. - * Browsers without View Transitions API get instant swap. - * ────────────────────────────────────────────────────────── */ -::view-transition-old(root), -::view-transition-new(root) { - animation-duration: 150ms; -} diff --git a/docs/_static/css/tmuxp.css b/docs/_static/css/tmuxp.css new file mode 100644 index 0000000000..326a8e765b --- /dev/null +++ b/docs/_static/css/tmuxp.css @@ -0,0 +1,12 @@ +/* Per-image aspect ratios for CLS reservation before load */ +img[src*="tmuxp-demo"] { + aspect-ratio: 888 / 589; +} + +img[src*="tmuxp-shell"] { + aspect-ratio: 878 / 109; +} + +img[src*="tmuxp-dev-screenshot"] { + aspect-ratio: 1030 / 605; +} diff --git a/docs/_templates/page.html b/docs/_templates/page.html deleted file mode 100644 index 7c0b561789..0000000000 --- a/docs/_templates/page.html +++ /dev/null @@ -1,76 +0,0 @@ -{% extends "!page.html" %} -{%- block extrahead %} - {{ super() }} - {%- for href in font_preload_hrefs|default([]) %} - - {%- endfor %} - {%- if font_faces is defined and font_faces %} - - {%- endif %} - {%- if theme_show_meta_manifest_tag == true %} - - {% endif -%} - {%- if theme_show_meta_og_tags == true %} - - - - - - - - - - - - - - - - {% endif -%} - {%- if theme_show_meta_app_icon_tags == true %} - - - - - - - - - - - - - - - - - - - - {% endif -%} -{% endblock %} diff --git a/docs/_templates/sidebar/brand.html b/docs/_templates/sidebar/brand.html deleted file mode 100644 index 7fe241c009..0000000000 --- a/docs/_templates/sidebar/brand.html +++ /dev/null @@ -1,18 +0,0 @@ - diff --git a/docs/_templates/sidebar/projects.html b/docs/_templates/sidebar/projects.html deleted file mode 100644 index f70e6fe032..0000000000 --- a/docs/_templates/sidebar/projects.html +++ /dev/null @@ -1,84 +0,0 @@ - - diff --git a/docs/conf.py b/docs/conf.py index 208f183724..4451c405fb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -38,7 +38,8 @@ }, linkcode_resolve=make_linkcode_resolve(tmuxp, about["__github__"]), # tmuxp-specific overrides - html_css_files=["css/custom.css"], + theme_options={"mask_icon": "/_static/img/tmuxp.svg"}, + html_css_files=["css/tmuxp.css"], html_extra_path=["manifest.json"], html_favicon="_static/favicon.ico", aafig_format={"latex": "pdf", "html": "gif"}, diff --git a/uv.lock b/uv.lock index 36a3bce83d..90bcdedbae 100644 --- a/uv.lock +++ b/uv.lock @@ -394,7 +394,7 @@ wheels = [ [[package]] name = "gp-sphinx" version = "0.0.1a0" -source = { editable = "../gp-sphinx/packages/gp-sphinx" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fgp-sphinx&branch=init-2#c2fe249c8910e333da5c755f193fdb310224dd43" } dependencies = [ { name = "docutils" }, { name = "gp-libs" }, @@ -415,25 +415,6 @@ dependencies = [ { name = "sphinxext-rediraffe" }, ] -[package.metadata] -requires-dist = [ - { name = "docutils" }, - { name = "gp-libs" }, - { name = "linkify-it-py" }, - { name = "myst-parser" }, - { name = "sphinx", specifier = "<9" }, - { name = "sphinx-argparse-neo", marker = "extra == 'argparse'", editable = "../gp-sphinx/packages/sphinx-argparse-neo" }, - { name = "sphinx-autodoc-typehints" }, - { name = "sphinx-copybutton" }, - { name = "sphinx-design" }, - { name = "sphinx-fonts", editable = "../gp-sphinx/packages/sphinx-fonts" }, - { name = "sphinx-gptheme", editable = "../gp-sphinx/packages/sphinx-gptheme" }, - { name = "sphinx-inline-tabs" }, - { name = "sphinxext-opengraph" }, - { name = "sphinxext-rediraffe" }, -] -provides-extras = ["argparse"] - [[package]] name = "h11" version = "0.16.0" @@ -1235,7 +1216,7 @@ wheels = [ [[package]] name = "sphinx-argparse-neo" version = "0.0.1a0" -source = { editable = "../gp-sphinx/packages/sphinx-argparse-neo" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-argparse-neo&branch=init-2#c2fe249c8910e333da5c755f193fdb310224dd43" } dependencies = [ { name = "docutils" }, { name = "pygments" }, @@ -1243,13 +1224,6 @@ dependencies = [ { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, ] -[package.metadata] -requires-dist = [ - { name = "docutils" }, - { name = "pygments" }, - { name = "sphinx" }, -] - [[package]] name = "sphinx-autobuild" version = "2024.10.3" @@ -1382,26 +1356,20 @@ wheels = [ [[package]] name = "sphinx-fonts" version = "0.0.1a0" -source = { editable = "../gp-sphinx/packages/sphinx-fonts" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-fonts&branch=init-2#c2fe249c8910e333da5c755f193fdb310224dd43" } dependencies = [ { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, ] -[package.metadata] -requires-dist = [{ name = "sphinx" }] - [[package]] name = "sphinx-gptheme" version = "0.0.1a0" -source = { editable = "../gp-sphinx/packages/sphinx-gptheme" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-gptheme&branch=init-2#c2fe249c8910e333da5c755f193fdb310224dd43" } dependencies = [ { name = "furo" }, ] -[package.metadata] -requires-dist = [{ name = "furo" }] - [[package]] name = "sphinx-inline-tabs" version = "2025.12.21.14" @@ -1585,7 +1553,7 @@ dev = [ { name = "codecov" }, { name = "coverage" }, { name = "gp-libs" }, - { name = "gp-sphinx", editable = "../gp-sphinx/packages/gp-sphinx" }, + { name = "gp-sphinx", git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fgp-sphinx&branch=init-2" }, { name = "mypy" }, { name = "pillow" }, { name = "pytest" }, @@ -1594,7 +1562,7 @@ dev = [ { name = "pytest-rerunfailures" }, { name = "pytest-watcher" }, { name = "ruff" }, - { name = "sphinx-argparse-neo", editable = "../gp-sphinx/packages/sphinx-argparse-neo" }, + { name = "sphinx-argparse-neo", git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-argparse-neo&branch=init-2" }, { name = "sphinx-autobuild" }, { name = "types-docutils" }, { name = "types-pygments" }, @@ -1603,9 +1571,9 @@ dev = [ docs = [ { name = "aafigure" }, { name = "gp-libs" }, - { name = "gp-sphinx", editable = "../gp-sphinx/packages/gp-sphinx" }, + { name = "gp-sphinx", git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fgp-sphinx&branch=init-2" }, { name = "pillow" }, - { name = "sphinx-argparse-neo", editable = "../gp-sphinx/packages/sphinx-argparse-neo" }, + { name = "sphinx-argparse-neo", git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-argparse-neo&branch=init-2" }, { name = "sphinx-autobuild" }, ] lint = [ From 04341f86cf86aa6cc412138da3e4829e0eafc986 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 29 Mar 2026 10:24:57 -0500 Subject: [PATCH 4/7] =?UTF-8?q?docs(chore):=20Drop=20tmuxp.css=20=E2=80=94?= =?UTF-8?q?=20project-specific=20CLS=20rules=20not=20needed=20for=20docs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/_static/css/tmuxp.css | 12 ------------ docs/conf.py | 1 - 2 files changed, 13 deletions(-) delete mode 100644 docs/_static/css/tmuxp.css diff --git a/docs/_static/css/tmuxp.css b/docs/_static/css/tmuxp.css deleted file mode 100644 index 326a8e765b..0000000000 --- a/docs/_static/css/tmuxp.css +++ /dev/null @@ -1,12 +0,0 @@ -/* Per-image aspect ratios for CLS reservation before load */ -img[src*="tmuxp-demo"] { - aspect-ratio: 888 / 589; -} - -img[src*="tmuxp-shell"] { - aspect-ratio: 878 / 109; -} - -img[src*="tmuxp-dev-screenshot"] { - aspect-ratio: 1030 / 605; -} diff --git a/docs/conf.py b/docs/conf.py index 4451c405fb..c2afba8c45 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,7 +39,6 @@ linkcode_resolve=make_linkcode_resolve(tmuxp, about["__github__"]), # tmuxp-specific overrides theme_options={"mask_icon": "/_static/img/tmuxp.svg"}, - html_css_files=["css/tmuxp.css"], html_extra_path=["manifest.json"], html_favicon="_static/favicon.ico", aafig_format={"latex": "pdf", "html": "gif"}, From 37ea80f36f80c0a7095c77b3098c22c41d47fc1f Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 29 Mar 2026 11:19:29 -0500 Subject: [PATCH 5/7] py(deps): Update gp-sphinx packages to 1d48098 (py.typed + strict typing) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit why: gp-sphinx init-2 branch gained PEP 561 py.typed markers and strict mypy compliance across all 4 packages in the typing(feat[py.typed]) commit. what: - uv.lock: bump all 4 gp-sphinx packages from c2fe249 → 1d48098 --- uv.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/uv.lock b/uv.lock index 90bcdedbae..c33d33226f 100644 --- a/uv.lock +++ b/uv.lock @@ -394,7 +394,7 @@ wheels = [ [[package]] name = "gp-sphinx" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fgp-sphinx&branch=init-2#c2fe249c8910e333da5c755f193fdb310224dd43" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fgp-sphinx&branch=init-2#1d48098a963ea0fec67555aedff6827b221aab2a" } dependencies = [ { name = "docutils" }, { name = "gp-libs" }, @@ -1216,7 +1216,7 @@ wheels = [ [[package]] name = "sphinx-argparse-neo" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-argparse-neo&branch=init-2#c2fe249c8910e333da5c755f193fdb310224dd43" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-argparse-neo&branch=init-2#1d48098a963ea0fec67555aedff6827b221aab2a" } dependencies = [ { name = "docutils" }, { name = "pygments" }, @@ -1356,7 +1356,7 @@ wheels = [ [[package]] name = "sphinx-fonts" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-fonts&branch=init-2#c2fe249c8910e333da5c755f193fdb310224dd43" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-fonts&branch=init-2#1d48098a963ea0fec67555aedff6827b221aab2a" } dependencies = [ { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, @@ -1365,7 +1365,7 @@ dependencies = [ [[package]] name = "sphinx-gptheme" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-gptheme&branch=init-2#c2fe249c8910e333da5c755f193fdb310224dd43" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-gptheme&branch=init-2#1d48098a963ea0fec67555aedff6827b221aab2a" } dependencies = [ { name = "furo" }, ] From 91b277b088c38db19d82c3f9d30ad4597be9f47b Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 29 Mar 2026 11:49:34 -0500 Subject: [PATCH 6/7] py(deps): Update gp-sphinx to d5dfb2f (actually commit py.typed files) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit why: 1d48098 claimed py.typed but files were untracked — d5dfb2f fixes this. what: - uv.lock: bump all 4 gp-sphinx packages from 1d48098 → d5dfb2f --- uv.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/uv.lock b/uv.lock index c33d33226f..1e67fd0668 100644 --- a/uv.lock +++ b/uv.lock @@ -394,7 +394,7 @@ wheels = [ [[package]] name = "gp-sphinx" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fgp-sphinx&branch=init-2#1d48098a963ea0fec67555aedff6827b221aab2a" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fgp-sphinx&branch=init-2#d5dfb2fa77553b9f4c00fa88ea2581414807d229" } dependencies = [ { name = "docutils" }, { name = "gp-libs" }, @@ -1216,7 +1216,7 @@ wheels = [ [[package]] name = "sphinx-argparse-neo" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-argparse-neo&branch=init-2#1d48098a963ea0fec67555aedff6827b221aab2a" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-argparse-neo&branch=init-2#d5dfb2fa77553b9f4c00fa88ea2581414807d229" } dependencies = [ { name = "docutils" }, { name = "pygments" }, @@ -1356,7 +1356,7 @@ wheels = [ [[package]] name = "sphinx-fonts" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-fonts&branch=init-2#1d48098a963ea0fec67555aedff6827b221aab2a" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-fonts&branch=init-2#d5dfb2fa77553b9f4c00fa88ea2581414807d229" } dependencies = [ { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, @@ -1365,7 +1365,7 @@ dependencies = [ [[package]] name = "sphinx-gptheme" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-gptheme&branch=init-2#1d48098a963ea0fec67555aedff6827b221aab2a" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-gptheme&branch=init-2#d5dfb2fa77553b9f4c00fa88ea2581414807d229" } dependencies = [ { name = "furo" }, ] From 3e7d836c0c514eb381bfba3b76119d88ba3ad6f6 Mon Sep 17 00:00:00 2001 From: Tony Narlock Date: Sun, 29 Mar 2026 12:19:22 -0500 Subject: [PATCH 7/7] py(deps): Update gp-sphinx to b39dbd2 (TypedDict typing improvements) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit why: gp-sphinx gained FooterIconDict/FuroThemeOptions/FontConfig TypedDicts, object annotations for argparse fields, and SetupDict for setup() returns. what: - uv.lock: bump all 4 packages from d5dfb2f → b39dbd2 --- uv.lock | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/uv.lock b/uv.lock index 1e67fd0668..3f7265adce 100644 --- a/uv.lock +++ b/uv.lock @@ -394,7 +394,7 @@ wheels = [ [[package]] name = "gp-sphinx" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fgp-sphinx&branch=init-2#d5dfb2fa77553b9f4c00fa88ea2581414807d229" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fgp-sphinx&branch=init-2#b39dbd2e4c0075221054a012a273706f79806971" } dependencies = [ { name = "docutils" }, { name = "gp-libs" }, @@ -1216,7 +1216,7 @@ wheels = [ [[package]] name = "sphinx-argparse-neo" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-argparse-neo&branch=init-2#d5dfb2fa77553b9f4c00fa88ea2581414807d229" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-argparse-neo&branch=init-2#b39dbd2e4c0075221054a012a273706f79806971" } dependencies = [ { name = "docutils" }, { name = "pygments" }, @@ -1356,7 +1356,7 @@ wheels = [ [[package]] name = "sphinx-fonts" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-fonts&branch=init-2#d5dfb2fa77553b9f4c00fa88ea2581414807d229" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-fonts&branch=init-2#b39dbd2e4c0075221054a012a273706f79806971" } dependencies = [ { name = "sphinx", version = "8.1.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" }, { name = "sphinx", version = "8.2.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" }, @@ -1365,7 +1365,7 @@ dependencies = [ [[package]] name = "sphinx-gptheme" version = "0.0.1a0" -source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-gptheme&branch=init-2#d5dfb2fa77553b9f4c00fa88ea2581414807d229" } +source = { git = "https://github.com/git-pull/gp-sphinx?subdirectory=packages%2Fsphinx-gptheme&branch=init-2#b39dbd2e4c0075221054a012a273706f79806971" } dependencies = [ { name = "furo" }, ]