docs: Complete documentation site, add autodoc extensions, and MystLexer

docs/_ext/argparse_neo_demo.py

@@ -0,0 +1,64 @@
+"""Demo parser factories for the sphinx-argparse-neo docs page."""
+
+from __future__ import annotations
+
+import argparse
+import textwrap
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Return a parser with groups, subcommands, and example epilogs."""
+    parser = argparse.ArgumentParser(
+        prog="gp-demo",
+        description="Inspect and synchronize documentation metadata.",
+    )
+    parser.add_argument(
+        "--format",
+        choices=["table", "json"],
+        default="table",
+        help="output format",
+    )
+    parser.add_argument(
+        "--jobs",
+        type=int,
+        default=4,
+        help="number of worker jobs",
+    )
+
+    subcommands = parser.add_subparsers(dest="command")
+
+    sync = subcommands.add_parser(
+        "sync",
+        help="synchronize package docs",
+        description="Synchronize package metadata into the docs site.",
+        epilog=textwrap.dedent(
+            """
+            examples:
+                gp-demo sync packages/sphinx-fonts
+                gp-demo sync packages/sphinx-gptheme
+
+            Machine-readable output examples:
+                gp-demo sync --format json packages/sphinx-fonts
+            """
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    sync.add_argument("target", metavar="PACKAGE", help="package to synchronize")
+    sync.add_argument(
+        "--strict",
+        action="store_true",
+        help="fail on missing docs coverage",
+    )
+
+    doctor = subcommands.add_parser(
+        "doctor",
+        help="check docs build health",
+        description="Run validation checks for the documentation site.",
+    )
+    doctor.add_argument(
+        "--warnings-as-errors",
+        action="store_true",
+        help="treat warnings as fatal",
+    )
+
+    return parser

docs/_ext/demo_cli.py

@@ -0,0 +1,86 @@
+"""Synthetic argparse parser factory used by the docs site.
+
+Examples
+--------
+>>> parser = create_parser()
+>>> parser.prog
+'myapp'
+>>> parser.parse_args(["mysubcommand", "--output", "dist"]).output
+'dist'
+"""
+
+from __future__ import annotations
+
+import argparse
+
+
+def create_parser() -> argparse.ArgumentParser:
+    """Return a parser that exercises the extension's rendering features.
+
+    Examples
+    --------
+    >>> parser = create_parser()
+    >>> parser.prog
+    'myapp'
+    """
+    parser = argparse.ArgumentParser(
+        prog="myapp",
+        description="Example CLI showing how sphinx-argparse-neo renders parsers.",
+    )
+    parser.add_argument(
+        "--verbose",
+        "-v",
+        action="store_true",
+        help="Enable verbose output.",
+    )
+    parser.add_argument(
+        "--config",
+        default="pyproject.toml",
+        metavar="PATH",
+        help="Path to configuration file.",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    sub1 = subparsers.add_parser(
+        "mysubcommand",
+        help="Run the primary task.",
+        description="Execute the primary task with configurable output.",
+    )
+    sub1.add_argument(
+        "--output",
+        "-o",
+        default="build",
+        metavar="DIR",
+        help="Output directory.",
+    )
+    sub1.add_argument(
+        "--format",
+        choices=["text", "json"],
+        default="text",
+        help="Output format.",
+    )
+    sub1.add_argument(
+        "--clean",
+        action="store_true",
+        help="Remove previous output first.",
+    )
+
+    sub2 = subparsers.add_parser(
+        "myothersubcommand",
+        help="Run a secondary task.",
+        description="Execute a secondary task with network options.",
+    )
+    sub2.add_argument(
+        "--port",
+        type=int,
+        default=8000,
+        help="Port number.",
+    )
+    sub2.add_argument(
+        "--host",
+        default="localhost",
+        help="Host to bind to.",
+    )
+
+    return parser

docs/_ext/docutils_demo.py

@@ -0,0 +1,90 @@
+"""Synthetic directives and roles for live autodoc-docutils demos.
+
+Examples
+--------
+>>> DemoBadgeDirective.required_arguments
+1
+>>> demo_badge_role.content
+True
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+
+if t.TYPE_CHECKING:
+    from docutils.parsers.rst.states import Inliner
+
+
+class DemoBadgeDirective(Directive):
+    """Render a short badge-like paragraph for directive demos."""
+
+    required_arguments = 1
+    optional_arguments = 0
+    final_argument_whitespace = True
+    has_content = False
+    option_spec: t.ClassVar[dict[str, t.Any]] = {"class": directives.class_option}
+
+    def run(self) -> list[nodes.Node]:
+        """Return a paragraph node for the requested badge label."""
+        paragraph = nodes.paragraph(text=f"demo badge: {self.arguments[0]}")
+        paragraph["classes"].extend(self.options.get("class", []))
+        return [paragraph]
+
+
+class DemoCalloutDirective(Directive):
+    """Render a simple titled container for directive demos."""
+
+    required_arguments = 0
+    optional_arguments = 0
+    has_content = True
+    option_spec: t.ClassVar[dict[str, t.Any]] = {
+        "title": directives.unchanged_required,
+    }
+
+    def run(self) -> list[nodes.Node]:
+        """Return a container with an optional title and paragraph content."""
+        container = nodes.container()
+        if "title" in self.options:
+            container += nodes.strong(text=self.options["title"])
+        if self.content:
+            container += nodes.paragraph(text=" ".join(self.content))
+        return [container]
+
+
+def demo_badge_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]]:
+    """Return a literal node with badge-style classes.
+
+    Examples
+    --------
+    >>> nodes_, messages = demo_badge_role(
+    ...     "demo-badge",
+    ...     ":demo-badge:`Alpha`",
+    ...     "Alpha",
+    ...     1,
+    ...     None,
+    ... )
+    >>> nodes_[0].astext()
+    'Alpha'
+    >>> messages
+    []
+    """
+    merged_options = options or {}
+    classes = ["demo-badge"]
+    classes.extend(merged_options.get("class", []))
+    return [nodes.literal(rawtext, text, classes=classes)], []
+
+
+demo_badge_role.options = {"class": directives.class_option}
+demo_badge_role.content = True