gencodo-py 0.1.0__py3-none-any.whl

gencodo/__init__.py

@@ -0,0 +1,23 @@
+"""gencodo -- Generate CLI reference documentation from argparse-based applications."""
+
+from gencodo._core import gen_docs, gen_docs_tree, get_bundled_templates
+from gencodo._types import (
+    Command,
+    CommandGroup,
+    ExampleInfo,
+    FlagInfo,
+    TemplateInfo,
+)
+
+__all__ = [
+    "Command",
+    "CommandGroup",
+    "ExampleInfo",
+    "FlagInfo",
+    "TemplateInfo",
+    "gen_docs",
+    "gen_docs_tree",
+    "get_bundled_templates",
+]
+
+__version__ = "0.1.0"

gencodo/_core.py

@@ -0,0 +1,287 @@
+"""Core documentation generation logic for gencodo."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.resources
+import pathlib
+import re
+from collections.abc import Callable, Sequence
+from typing import Literal, TextIO
+
+from gencodo._jinja_env import _make_jinja_env
+from gencodo._types import (
+    Command,
+    CommandGroup,
+    ExampleInfo,
+    FlagInfo,
+    TemplateInfo,
+)
+
+__all__ = [
+    "gen_docs",
+    "gen_docs_tree",
+    "get_bundled_templates",
+]
+
+
+def _instantiate_command(command_class: type[Command]) -> Command:
+    """Instantiate a command class for parser introspection.
+
+    Tries command_class(None) first (craft_cli compatible),
+    then command_class() for simple classes.
+    """
+    try:
+        return command_class(None)  # type: ignore[call-arg]
+    except TypeError:
+        return command_class()  # type: ignore[call-arg]
+
+
+def _extract_flags(command_class: type[Command]) -> list[FlagInfo]:
+    """Extract optional flags from a command class as FlagInfo objects.
+
+    Positional arguments and suppressed flags are excluded.
+    The longest option string is used as the flag name.
+
+    Args:
+        command_class: A command class satisfying the Command protocol.
+
+    Returns:
+        A list of FlagInfo objects for the command's optional flags.
+    """
+    parser = argparse.ArgumentParser(prog=command_class.name, add_help=False)
+    _instantiate_command(command_class).fill_parser(parser)
+    flags: list[FlagInfo] = []
+    for action in parser._actions:
+        if not action.option_strings:
+            continue
+        if action.help == argparse.SUPPRESS:
+            continue
+        name = max(action.option_strings, key=len)
+        usage = action.help or ""
+        if action.default is None or action.default is argparse.SUPPRESS:
+            default = ""
+        else:
+            default = str(action.default)
+        flags.append(FlagInfo(name=name, usage=usage, default_value=default))
+    return flags
+
+
+def _infer_related(
+    command_class: type[Command],
+    command_groups: Sequence[CommandGroup],
+) -> list[str]:
+    """Determine the list of related command names for a command.
+
+    If the command has explicit ``related_commands``, those are validated
+    and returned. Otherwise, non-hidden siblings in the same group are returned.
+
+    Args:
+        command_class: The command class to find related commands for.
+        command_groups: All command groups in the application.
+
+    Returns:
+        A list of related command names.
+
+    Raises:
+        ValueError: If an explicit related command name is not found.
+    """
+    if command_class.related_commands is not None:
+        all_names = {c.name for g in command_groups for c in g.commands}
+        for name in command_class.related_commands:
+            if name not in all_names:
+                raise ValueError(
+                    f"related command {name!r} not found in command_groups"
+                )
+        return list(command_class.related_commands)
+    for group in command_groups:
+        if command_class in group.commands:
+            siblings = [
+                c.name
+                for c in group.commands
+                if c is not command_class and not c.hidden
+            ]
+            return sorted(siblings)
+    return []
+
+
+def _build_template_context(
+    command_class: type[Command],
+    appname: str,
+    command_groups: Sequence[CommandGroup],
+) -> dict[str, object]:
+    """Build the complete Jinja2 template context dict for a command.
+
+    Args:
+        command_class: The command class to build context for.
+        appname: The application name used in usage strings.
+        command_groups: All command groups in the application.
+
+    Returns:
+        A dict with keys: ref, command_name, short, long, synopsis,
+        examples, flags, related_commands, heading_len, appname.
+
+    Raises:
+        ValueError: If command_name or help_msg is empty.
+    """
+    command_name = command_class.name
+    short = command_class.help_msg
+    if not command_name:
+        raise ValueError("command_name must not be empty")
+    if not short:
+        raise ValueError("short (help_msg) must not be empty")
+
+    long = (command_class.overview or "").strip()
+
+    parser = argparse.ArgumentParser(
+        prog=f"{appname} {command_name}", add_help=False
+    )
+    _instantiate_command(command_class).fill_parser(parser)
+    raw_usage = parser.format_usage()
+    synopsis = re.sub(r"^usage:\s*", "", raw_usage).strip()
+
+    examples = [
+        ExampleInfo(info=info, usage=usage)
+        for info, usage in command_class.examples
+    ]
+
+    flags = _extract_flags(command_class)
+    related_commands = _infer_related(command_class, command_groups)
+    heading_len = len(command_name)
+    ref = command_name.replace("-", "_").replace(" ", "_")
+
+    return {
+        "ref": ref,
+        "command_name": command_name,
+        "short": short,
+        "long": long,
+        "synopsis": synopsis,
+        "examples": examples,
+        "flags": flags,
+        "related_commands": related_commands,
+        "heading_len": heading_len,
+        "appname": appname,
+    }
+
+
+def gen_docs(
+    command_class: type[Command],
+    writer: TextIO,
+    template: str,
+    appname: str,
+    command_groups: Sequence[CommandGroup],
+) -> None:
+    """Render documentation for a single command to a writer.
+
+    Args:
+        command_class: The command class to document.
+        writer: A text stream to write the rendered output to.
+        template: A Jinja2 template string for the command page.
+        appname: The application name used in usage strings.
+        command_groups: All command groups (used for related commands).
+    """
+    env = _make_jinja_env()
+    compiled = env.from_string(template)
+    context = _build_template_context(command_class, appname, command_groups)
+    writer.write(compiled.render(context))
+
+
+def gen_docs_tree(
+    appname: str,
+    command_groups: Sequence[CommandGroup],
+    output_dir: pathlib.Path,
+    templates: TemplateInfo,
+    file_prepender: Callable[[str], str] | None = None,
+    file_extension: str = ".md",
+) -> list[str]:
+    """Generate a documentation tree for all non-hidden commands.
+
+    Creates one file per command plus an index file in the output directory.
+
+    Args:
+        appname: The application name used in usage strings.
+        command_groups: All command groups in the application.
+        output_dir: Directory to write generated files into (created if needed).
+        templates: Template configuration for index and command pages.
+        file_prepender: Optional callable returning a string to prepend to each file.
+        file_extension: File extension for command pages (default: ".md").
+
+    Returns:
+        A list of generated command filenames (not including the index).
+    """
+    output_dir = pathlib.Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    env = _make_jinja_env()
+    compiled_cmd = env.from_string(templates.command_template)
+    compiled_idx = env.from_string(templates.index_template)
+
+    generated: list[str] = []
+    files_context: list[dict[str, str]] = []
+
+    for group in command_groups:
+        for cmd in group.commands:
+            if cmd.hidden:
+                continue
+            filename = cmd.name.replace(" ", "-") + file_extension
+            context = _build_template_context(cmd, appname, command_groups)
+            content = compiled_cmd.render(context)
+            if file_prepender is not None:
+                content = file_prepender(filename) + content
+            (output_dir / filename).write_text(content, encoding="utf-8")
+            generated.append(filename)
+            files_context.append(
+                {
+                    "filename": filename,
+                    "command_name": cmd.name,
+                    "short": cmd.help_msg,
+                    "group_name": group.name,
+                }
+            )
+
+    idx_content = compiled_idx.render(files=files_context, appname=appname)
+    if file_prepender is not None:
+        idx_content = file_prepender(templates.index_file_name) + idx_content
+    (output_dir / templates.index_file_name).write_text(
+        idx_content, encoding="utf-8"
+    )
+
+    return generated
+
+
+def get_bundled_templates(
+    format: Literal["rst", "md"] = "rst",
+    index_file_name: str | None = None,
+) -> TemplateInfo:
+    """Load bundled default templates for the given format.
+
+    Args:
+        format: Template format -- "rst" for reStructuredText, "md" for Markdown.
+        index_file_name: Override the default index filename.
+            Defaults to "index.rst" or "index.md" based on format.
+
+    Returns:
+        A TemplateInfo with the bundled templates loaded.
+
+    Raises:
+        ValueError: If format is not "rst" or "md".
+    """
+    if format not in ("rst", "md"):
+        raise ValueError(f"format must be 'rst' or 'md', got {format!r}")
+
+    templates_pkg = importlib.resources.files("gencodo") / "templates" / format
+    command_template = (
+        (templates_pkg / f"command.{format}.j2").read_text(encoding="utf-8")
+    )
+    index_template = (
+        (templates_pkg / f"index.{format}.j2").read_text(encoding="utf-8")
+    )
+
+    if index_file_name is None:
+        index_file_name = f"index.{format}"
+
+    return TemplateInfo(
+        index_file_name=index_file_name,
+        index_template=index_template,
+        command_template=command_template,
+    )

gencodo/_jinja_env.py

@@ -0,0 +1,31 @@
+"""Jinja2 environment configuration for gencodo."""
+
+from __future__ import annotations
+
+from jinja2 import Environment, StrictUndefined
+from jinja2.filters import do_indent
+
+
+def _make_jinja_env() -> Environment:
+    """Create a configured Jinja2 Environment for documentation generation.
+
+    Returns:
+        A Jinja2 Environment with custom filters for documentation rendering.
+    """
+    env = Environment(
+        autoescape=False,
+        undefined=StrictUndefined,
+        trim_blocks=True,
+        lstrip_blocks=True,
+        keep_trailing_newline=True,
+    )
+
+    def _indent(s: str, width: int = 4, *, blank: bool = False) -> str:
+        return do_indent(s, width=width, first=True, blank=blank)
+
+    def _repeat(s: str, n: int) -> str:
+        return s * n
+
+    env.filters["indent"] = _indent
+    env.filters["repeat"] = _repeat
+    return env

gencodo/_types.py

@@ -0,0 +1,92 @@
+"""Type definitions for gencodo: protocols, dataclasses, and named tuples."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+from collections.abc import Sequence
+from typing import NamedTuple, Protocol, runtime_checkable
+
+__all__ = [
+    "Command",
+    "CommandGroup",
+    "ExampleInfo",
+    "FlagInfo",
+    "TemplateInfo",
+]
+
+
+@runtime_checkable
+class Command(Protocol):
+    """Protocol that any CLI command class must satisfy.
+
+    Any class with these attributes and methods can be used with gencodo
+    via structural subtyping -- no inheritance required.
+    """
+
+    name: str
+    """The command name as invoked on the command line."""
+    help_msg: str
+    """Short one-line help string."""
+    overview: str
+    """Longer description of the command (may be multi-line)."""
+    hidden: bool
+    """Whether this command should be excluded from generated documentation."""
+    examples: list[tuple[str, str]]
+    """List of (description, command_string) example pairs."""
+    related_commands: list[str] | None
+    """Explicit list of related command names, or None to infer from siblings."""
+
+    def fill_parser(self, parser: argparse.ArgumentParser) -> None:
+        """Add command-specific arguments to the parser."""
+        ...
+
+
+class CommandGroup(NamedTuple):
+    """A named group of commands."""
+
+    name: str
+    """Human-readable group name."""
+    commands: Sequence[type[Command]]
+    """Command classes in this group."""
+
+
+@dataclasses.dataclass(frozen=True, slots=True, eq=True, order=False)
+class ExampleInfo:
+    """Structured representation of a usage example."""
+
+    info: str
+    """Human-readable description of what the example demonstrates."""
+    usage: str
+    """The literal command string for the example."""
+
+
+@dataclasses.dataclass(frozen=True, slots=True, eq=True, order=False)
+class FlagInfo:
+    """Structured representation of a single CLI flag."""
+
+    name: str
+    """The flag name as it appears on the command line (e.g., '--verbose')."""
+    usage: str
+    """One-line description of the flag's purpose."""
+    default_value: str
+    """The default value shown in documentation."""
+
+
+@dataclasses.dataclass(frozen=True, slots=True, eq=True, order=False)
+class TemplateInfo:
+    """Jinja2 template configuration for documentation generation."""
+
+    index_file_name: str
+    """Output filename for the index document."""
+    index_template: str
+    """Jinja2 template string for the index document."""
+    command_template: str
+    """Jinja2 template string for per-command documents."""
+
+    def __post_init__(self) -> None:
+        """Validate that no field is empty or whitespace-only."""
+        for field_name in ("index_file_name", "index_template", "command_template"):
+            value = getattr(self, field_name)
+            if not value.strip():
+                raise ValueError(f"TemplateInfo.{field_name} must not be empty")

gencodo/templates/md/command.md.j2

@@ -0,0 +1,43 @@
+# {{ command_name }}
+
+{{ short }}
+
+**Usage:**
+
+```
+{{ synopsis }}
+```
+
+## Overview
+
+{{ long }}
+
+{% if flags %}
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+{% for flag in flags %}
+| `{{ flag.name }}` | {{ flag.usage }} | {% if flag.default_value %}`{{ flag.default_value }}`{% endif %} |
+{% endfor %}
+
+{% endif %}
+{% if examples %}
+## Examples
+
+{% for example in examples %}
+**{{ example.info }}**
+
+```
+{{ example.usage }}
+```
+
+{% endfor %}
+{% endif %}
+{% if related_commands %}
+## See also
+
+{% for cmd in related_commands %}
+- [{{ cmd }}]({{ cmd }}.md)
+{% endfor %}
+{% endif %}

gencodo/templates/md/index.md.j2

@@ -0,0 +1,25 @@
+# CLI Reference
+
+Command-line interface reference for **{{ appname }}**.
+
+This reference documentation is automatically generated from the command
+definitions and provides detailed information about each available command.
+
+## Available Commands
+
+{% for group_name, group_files in files | groupby('group_name') %}
+### {{ group_name }}
+
+{% for file in group_files %}
+- [{{ file.command_name }}]({{ file.filename }}) -- {{ file.short }}
+{% endfor %}
+
+{% endfor %}
+
+## Quick Reference Table
+
+| Command | Description |
+|---------|-------------|
+{% for file in files %}
+| [{{ file.command_name }}]({{ file.filename }}) | {{ file.short }} |
+{% endfor %}

gencodo/templates/rst/command.rst.j2

@@ -0,0 +1,54 @@
+.. _ref_{{ ref }}:
+
+{{ command_name }}
+{{ '=' | repeat(heading_len) }}
+
+{{ short }}
+
+**Usage:**
+
+.. code-block:: bash
+
+   {{ synopsis }}
+
+Overview
+--------
+
+{{ long }}
+
+{% if flags %}
+Options
+-------
+
+{% for flag in flags %}
+.. option:: {{ flag.name }}
+
+   {{ flag.usage | indent(3) }}
+   {% if flag.default_value %}
+
+   Default: ``{{ flag.default_value }}``
+   {% endif %}
+
+{% endfor %}
+{% endif %}
+{% if examples %}
+Examples
+--------
+
+{% for example in examples %}
+**{{ example.info }}**
+
+.. code-block:: bash
+
+   {{ example.usage }}
+
+{% endfor %}
+{% endif %}
+{% if related_commands %}
+See also
+--------
+
+{% for cmd in related_commands %}
+- :ref:`{{ cmd }} <ref_{{ cmd | replace('-', '_') | replace(' ', '_') }}>`
+{% endfor %}
+{% endif %}

gencodo/templates/rst/index.rst.j2

@@ -0,0 +1,39 @@
+.. _cli_reference:
+
+CLI Reference
+=============
+
+Command-line interface reference for **{{ appname }}**.
+
+This reference documentation is automatically generated from the command
+definitions and provides detailed information about each available command.
+
+Available Commands
+------------------
+
+{% for group_name, group_files in files | groupby('group_name') %}
+{{ group_name }}
+{{ '~' | repeat(group_name | length) }}
+
+.. toctree::
+   :maxdepth: 1
+
+{% for file in group_files %}
+   {{ file.filename[:-4] }}
+{% endfor %}
+
+{% endfor %}
+
+Quick Reference Table
+---------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Command
+     - Description
+{% for file in files %}
+   * - :ref:`{{ file.command_name }} <ref_{{ file.command_name | replace('-', '_') | replace(' ', '_') }}>`
+     - {{ file.short }}
+{% endfor %}

gencodo_py-0.1.0.dist-info/METADATA

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: gencodo-py
+Version: 0.1.0
+Summary: Generate CLI reference documentation from argparse-based applications using Jinja2 templates
+Project-URL: Homepage, https://github.com/canonical/gencodo-py
+Project-URL: Issues, https://github.com/canonical/gencodo-py/issues
+Author: gencodo contributors
+License-Expression: LGPL-3.0-only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# gencodo-py
+
+Generate CLI reference documentation from argparse-based applications using Jinja2 templates.
+
+## Installation
+
+```bash
+pip install gencodo-py
+```
+
+## Quick Start
+
+Define your CLI commands as plain Python classes (no base class required):
+
+```python
+import argparse
+
+class GreetCommand:
+    name = "greet"
+    help_msg = "Greet a specific person"
+    overview = "Personalize your greeting by specifying a name."
+    hidden = False
+    examples = [("Greet Alice", "myapp greet Alice")]
+    related_commands = None
+
+    def fill_parser(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument("name", help="Name to greet")
+        parser.add_argument("--formal", action="store_true", default=False,
+                            help="Use formal style")
+```
+
+Generate documentation:
+
+```python
+from gencodo import CommandGroup, gen_docs_tree, get_bundled_templates
+
+groups = [CommandGroup(name="Greetings", commands=[GreetCommand])]
+templates = get_bundled_templates("md")  # or "rst"
+
+gen_docs_tree(
+    appname="myapp",
+    command_groups=groups,
+    output_dir="docs/cli-ref",
+    templates=templates,
+)
+```
+
+## API Reference
+
+### Types
+
+- **`Command`** -- Protocol that any CLI command class must satisfy (structural subtyping).
+- **`CommandGroup`** -- NamedTuple grouping commands under a name.
+- **`ExampleInfo`** -- Dataclass for a usage example (info, usage).
+- **`FlagInfo`** -- Dataclass for a CLI flag (name, usage, default_value).
+- **`TemplateInfo`** -- Dataclass for Jinja2 template configuration.
+
+### Functions
+
+- **`gen_docs(command_class, writer, template, appname, command_groups)`** -- Render docs for a single command to a TextIO writer.
+- **`gen_docs_tree(appname, command_groups, output_dir, templates, ...)`** -- Generate a full documentation tree (one file per command + index).
+- **`get_bundled_templates(format="rst", index_file_name=None)`** -- Load bundled reST or Markdown templates.
+
+### Command Protocol
+
+Your command classes need these attributes/methods:
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `name` | `str` | Command name |
+| `help_msg` | `str` | Short help string |
+| `overview` | `str` | Longer description |
+| `hidden` | `bool` | Exclude from docs if True |
+| `examples` | `list[tuple[str, str]]` | (description, command) pairs |
+| `related_commands` | `list[str] \| None` | Explicit related commands, or None to auto-infer |
+| `fill_parser(parser)` | method | Add arguments to an ArgumentParser |
+
+## Template Customization
+
+### Bundled Templates
+
+Use `get_bundled_templates("rst")` or `get_bundled_templates("md")` for the built-in templates.
+
+### Custom Templates
+
+Pass your own Jinja2 template strings via `TemplateInfo`:
+
+```python
+from gencodo import TemplateInfo
+
+templates = TemplateInfo(
+    index_file_name="index.md",
+    index_template="# Commands\n{% for f in files %}...\n{% endfor %}",
+    command_template="# {{ command_name }}\n{{ short }}\n...",
+)
+```
+
+Available template variables for command templates:
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `ref` | `str` | Anchor reference (underscored name) |
+| `command_name` | `str` | Command name |
+| `short` | `str` | Short help message |
+| `long` | `str` | Overview text |
+| `synopsis` | `str` | Usage synopsis |
+| `examples` | `list[ExampleInfo]` | Usage examples |
+| `flags` | `list[FlagInfo]` | Optional flags |
+| `related_commands` | `list[str]` | Related command names |
+| `heading_len` | `int` | Length of command name |
+| `appname` | `str` | Application name |
+
+Custom Jinja2 filters available: `indent(width)`, `repeat(n)`.
+
+## License
+
+LGPL-3.0-only

gencodo_py-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+gencodo/__init__.py,sha256=jn-eancNlIWTvin_HqfjREHb8VzTHpwxnEG5j8z467k,467
+gencodo/_core.py,sha256=fx0HS35Ur20lHhC7g6gSHtYBmoB6ma91xAgefuGykOc,9421
+gencodo/_jinja_env.py,sha256=GadUxPluIB5y_G2VVnGZ_SpVTN7PGc9hf9Suat5DJos,859
+gencodo/_types.py,sha256=piDxKr0zanskQGmTV-Il6EKxGuvYeKBkTab41__EXtA,2907
+gencodo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gencodo/templates/md/command.md.j2,sha256=7lC23VA5hnotciY1FLClctMYqCQNqjbHtV80fWA-G0o,612
+gencodo/templates/md/index.md.j2,sha256=e9_2YZilPpj9JTcx4d5yu0tiJI8Ro-tetCo_GBlzm4I,648
+gencodo/templates/rst/command.rst.j2,sha256=agRAQdnSRGW3kR5QjWmWgcBeNHsCHziFI2O44tFfd38,741
+gencodo/templates/rst/index.rst.j2,sha256=iUGoAPRwzdHnZob-Gl1j6XnKVVkZEmR5cXJfdziPXu4,838
+gencodo_py-0.1.0.dist-info/METADATA,sha256=RqQF2hKFTsMIMuri35r6_twek8YSVX5jalvezLf2ero,4821
+gencodo_py-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+gencodo_py-0.1.0.dist-info/RECORD,,

gencodo_py-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any