gencodo-py 0.1.0__tar.gz

gencodo_py-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

gencodo_py-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+.claude/
+.pytest_cache/
+.venv/

gencodo_py-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+Initial release.
+
+- Protocol-based `Command` interface (no inheritance required)
+- `gen_docs()` for single-command documentation
+- `gen_docs_tree()` for full documentation trees
+- `get_bundled_templates()` with reST and Markdown formats
+- Jinja2-based template rendering with `indent` and `repeat` filters
+- `ExampleInfo`, `FlagInfo`, `TemplateInfo` dataclasses
+- `CommandGroup` named tuple for organizing commands
+- Automatic related-command inference from sibling commands
+- PEP 561 type stubs (`py.typed`)

gencodo_py-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,117 @@
+# 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/examples/demo_cli/app.py

@@ -0,0 +1,105 @@
+"""Example CLI app using plain argparse classes (no framework dependency).
+
+Each command class satisfies the gencodo.Command protocol via duck typing.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+
+class HelloCommand:
+    """Say hello to the world."""
+
+    name = "hello"
+    help_msg = "Say hello to the world"
+    overview = (
+        "Prints a friendly hello message to standard output.\n\n"
+        "This is the simplest possible command with no arguments."
+    )
+    hidden = False
+    examples = [
+        ("Say hello", "democli hello"),
+    ]
+    related_commands = None
+
+    def __init__(self, config=None):
+        self.config = config
+
+    def fill_parser(self, parser: argparse.ArgumentParser) -> None:
+        pass
+
+
+class GreetCommand:
+    """Greet a specific person."""
+
+    name = "greet"
+    help_msg = "Greet a specific person"
+    overview = (
+        "The greet command allows you to personalize your greeting by specifying\n"
+        "a name. You can also customize the greeting style and add an optional\n"
+        "message suffix.\n\n"
+        "This command demonstrates how to use positional and optional arguments."
+    )
+    hidden = False
+    examples = [
+        ("Greet Alice", "democli greet Alice"),
+        ("Greet Bob formally", "democli greet Bob --formal"),
+        ("Greet Charlie with enthusiasm", "democli greet Charlie --enthusiasm 5"),
+        ("Greet with a suffix", "democli greet Alice --suffix ', have a great day!'"),
+    ]
+    related_commands = None
+
+    def __init__(self, config=None):
+        self.config = config
+
+    def fill_parser(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument("name", help="Name of the person to greet")
+        parser.add_argument(
+            "--formal",
+            action="store_true",
+            default=False,
+            help="Use formal greeting style",
+        )
+        parser.add_argument(
+            "--enthusiasm",
+            type=int,
+            default=1,
+            help="Enthusiasm level (1-5)",
+        )
+        parser.add_argument(
+            "--suffix",
+            default=None,
+            help="Optional message suffix",
+        )
+
+
+class FarewellCommand:
+    """Say goodbye."""
+
+    name = "farewell"
+    help_msg = "Say goodbye"
+    overview = "Prints a farewell message. Supports formal and informal styles."
+    hidden = False
+    examples = [
+        ("Say farewell", "democli farewell"),
+        ("Formal farewell", "democli farewell --formal"),
+    ]
+    related_commands = None
+
+    def __init__(self, config=None):
+        self.config = config
+
+    def fill_parser(self, parser: argparse.ArgumentParser) -> None:
+        parser.add_argument(
+            "--formal",
+            action="store_true",
+            default=False,
+            help="Use formal farewell style",
+        )
+
+
+# Command groups for use with gencodo
+COMMAND_GROUPS = [
+    ("Greetings", [HelloCommand, GreetCommand, FarewellCommand]),
+]

gencodo_py-0.1.0/examples/demo_cli/docs_output/md/farewell.md

@@ -0,0 +1,38 @@
+# farewell
+
+Say goodbye
+
+**Usage:**
+
+```
+democli farewell [--formal]
+```
+
+## Overview
+
+Prints a farewell message. Supports formal and informal styles.
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--formal` | Use formal farewell style | `False` |
+
+## Examples
+
+**Say farewell**
+
+```
+democli farewell
+```
+
+**Formal farewell**
+
+```
+democli farewell --formal
+```
+
+## See also
+
+- [greet](greet.md)
+- [hello](hello.md)

gencodo_py-0.1.0/examples/demo_cli/docs_output/md/greet.md

@@ -0,0 +1,57 @@
+# greet
+
+Greet a specific person
+
+**Usage:**
+
+```
+democli greet [--formal] [--enthusiasm ENTHUSIASM] [--suffix SUFFIX]
+                     name
+```
+
+## Overview
+
+The greet command allows you to personalize your greeting by specifying
+a name. You can also customize the greeting style and add an optional
+message suffix.
+
+This command demonstrates how to use positional and optional arguments.
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--formal` | Use formal greeting style | `False` |
+| `--enthusiasm` | Enthusiasm level (1-5) | `1` |
+| `--suffix` | Optional message suffix |  |
+
+## Examples
+
+**Greet Alice**
+
+```
+democli greet Alice
+```
+
+**Greet Bob formally**
+
+```
+democli greet Bob --formal
+```
+
+**Greet Charlie with enthusiasm**
+
+```
+democli greet Charlie --enthusiasm 5
+```
+
+**Greet with a suffix**
+
+```
+democli greet Alice --suffix ', have a great day!'
+```
+
+## See also
+
+- [farewell](farewell.md)
+- [hello](hello.md)

gencodo_py-0.1.0/examples/demo_cli/docs_output/md/hello.md

@@ -0,0 +1,28 @@
+# hello
+
+Say hello to the world
+
+**Usage:**
+
+```
+democli hello
+```
+
+## Overview
+
+Prints a friendly hello message to standard output.
+
+This is the simplest possible command with no arguments.
+
+## Examples
+
+**Say hello**
+
+```
+democli hello
+```
+
+## See also
+
+- [farewell](farewell.md)
+- [greet](greet.md)

gencodo_py-0.1.0/examples/demo_cli/docs_output/md/index.md

@@ -0,0 +1,23 @@
+# CLI Reference
+
+Command-line interface reference for **democli**.
+
+This reference documentation is automatically generated from the command
+definitions and provides detailed information about each available command.
+
+## Available Commands
+
+### Greetings
+
+- [hello](hello.md) -- Say hello to the world
+- [greet](greet.md) -- Greet a specific person
+- [farewell](farewell.md) -- Say goodbye
+
+
+## Quick Reference Table
+
+| Command | Description |
+|---------|-------------|
+| [hello](hello.md) | Say hello to the world |
+| [greet](greet.md) | Greet a specific person |
+| [farewell](farewell.md) | Say goodbye |

gencodo_py-0.1.0/examples/demo_cli/docs_output/rst/farewell.rst

@@ -0,0 +1,47 @@
+.. _ref_farewell:
+
+farewell
+========
+
+Say goodbye
+
+**Usage:**
+
+.. code-block:: bash
+
+   democli farewell [--formal]
+
+Overview
+--------
+
+Prints a farewell message. Supports formal and informal styles.
+
+Options
+-------
+
+.. option:: --formal
+
+      Use formal farewell style
+
+   Default: ``False``
+
+Examples
+--------
+
+**Say farewell**
+
+.. code-block:: bash
+
+   democli farewell
+
+**Formal farewell**
+
+.. code-block:: bash
+
+   democli farewell --formal
+
+See also
+--------
+
+- :ref:`greet <ref_greet>`
+- :ref:`hello <ref_hello>`

gencodo_py-0.1.0/examples/demo_cli/docs_output/rst/greet.rst

@@ -0,0 +1,74 @@
+.. _ref_greet:
+
+greet
+=====
+
+Greet a specific person
+
+**Usage:**
+
+.. code-block:: bash
+
+   democli greet [--formal] [--enthusiasm ENTHUSIASM] [--suffix SUFFIX]
+                     name
+
+Overview
+--------
+
+The greet command allows you to personalize your greeting by specifying
+a name. You can also customize the greeting style and add an optional
+message suffix.
+
+This command demonstrates how to use positional and optional arguments.
+
+Options
+-------
+
+.. option:: --formal
+
+      Use formal greeting style
+
+   Default: ``False``
+
+.. option:: --enthusiasm
+
+      Enthusiasm level (1-5)
+
+   Default: ``1``
+
+.. option:: --suffix
+
+      Optional message suffix
+
+Examples
+--------
+
+**Greet Alice**
+
+.. code-block:: bash
+
+   democli greet Alice
+
+**Greet Bob formally**
+
+.. code-block:: bash
+
+   democli greet Bob --formal
+
+**Greet Charlie with enthusiasm**
+
+.. code-block:: bash
+
+   democli greet Charlie --enthusiasm 5
+
+**Greet with a suffix**
+
+.. code-block:: bash
+
+   democli greet Alice --suffix ', have a great day!'
+
+See also
+--------
+
+- :ref:`farewell <ref_farewell>`
+- :ref:`hello <ref_hello>`