click-docs 0.2.0__py3-none-any.whl

click_docs/__init__.py

@@ -0,0 +1,3 @@
+"""Top-level package for click_docs."""
+
+__version__ = "0.2.0"

click_docs/cli.py

@@ -0,0 +1,190 @@
+"""Command-line entry point for click-docs."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+from click.core import ParameterSource
+
+from .config import find_config
+from .generator import generate_docs
+from .loader import LoadError, load_command
+
+# Maps Python parameter names (underscores) to pyproject.toml keys (hyphens).
+# Note: "exclude" is intentionally absent — it needs tuple() coercion and is handled
+# as a special case in _apply_config.
+_PARAM_TO_CONFIG_KEY: dict[str, str] = {
+    "command_name": "command-name",
+    "program_name": "program-name",
+    "header_depth": "header-depth",
+    "style": "style",
+    "output": "output",
+    "depth": "depth",
+    "show_hidden": "show-hidden",
+    "list_subcommands": "list-subcommands",
+    "remove_ascii_art": "remove-ascii-art",
+    "full_command_path": "full-command-path",
+}
+
+
+def _apply_config(ctx: click.Context, config: dict[str, Any], kwargs: dict[str, Any]) -> dict[str, Any]:
+    """Override defaulted CLI params with values from config.
+
+    Args:
+        ctx: The Click context for the current invocation.
+        config: Dict of [tool.click-docs] values from pyproject.toml.
+        kwargs: Current parameter values keyed by Python name (underscores).
+
+    Returns:
+        Updated kwargs dict with config values applied where CLI used its default.
+    """
+    result = dict(kwargs)
+    for param, config_key in _PARAM_TO_CONFIG_KEY.items():
+        if ctx.get_parameter_source(param) == ParameterSource.DEFAULT and config_key in config:
+            result[param] = config[config_key]
+    if ctx.get_parameter_source("exclude") == ParameterSource.DEFAULT and "exclude" in config:
+        result["exclude"] = tuple(config["exclude"])
+    return result
+
+
+@click.command()
+@click.pass_context
+@click.argument("module_path")
+@click.option(
+    "--command-name",
+    default="cli",
+    show_default=True,
+    help="Dotted attribute path to the Click command object.",
+)
+@click.option(
+    "--program-name",
+    default=None,
+    help="Display name for the command in headings and usage lines.",
+)
+@click.option(
+    "--header-depth",
+    default=1,
+    show_default=True,
+    type=click.IntRange(1, 6),
+    help="Markdown header level for the command title (1-6).",
+)
+@click.option(
+    "--style",
+    default="plain",
+    show_default=True,
+    type=click.Choice(["plain", "table"]),
+    help="Options rendering style.",
+)
+@click.option(
+    "--output",
+    default=None,
+    metavar="FILE",
+    help="Write output to FILE instead of stdout.",
+)
+@click.option(
+    "--depth",
+    default=None,
+    type=click.IntRange(min=0),
+    metavar="N",
+    help="Maximum subcommand recursion depth (0=root only; default=unlimited).",
+)
+@click.option(
+    "--exclude",
+    multiple=True,
+    metavar="PATH",
+    help="Dotted command path to exclude (e.g. root.admin.reset). Repeatable.",
+)
+@click.option(
+    "--show-hidden",
+    is_flag=True,
+    default=False,
+    help="Include commands and options marked hidden=True.",
+)
+@click.option(
+    "--list-subcommands",
+    is_flag=True,
+    default=False,
+    help="Prepend a bulleted TOC of subcommands at the root level.",
+)
+@click.option(
+    "--remove-ascii-art",
+    is_flag=True,
+    default=False,
+    help=r"Strip \b-prefixed blocks (ASCII art) from help text.",
+)
+@click.option(
+    "--full-command-path",
+    is_flag=True,
+    default=False,
+    help="Use the full command path in headers (e.g. 'cli admin' instead of 'admin').",
+)
+def cli(
+    ctx: click.Context,
+    module_path: str,
+    command_name: str,
+    program_name: str | None,
+    header_depth: int,
+    style: str,
+    output: str | None,
+    depth: int | None,
+    exclude: tuple[str, ...],
+    show_hidden: bool,
+    list_subcommands: bool,
+    remove_ascii_art: bool,
+    full_command_path: bool,
+) -> None:
+    """
+    Generate Markdown documentation for a Click application.
+
+    MODULE_PATH is a file system path to the Python module containing the Click command.
+    """
+    resolved = _apply_config(
+        ctx,
+        find_config(),
+        {
+            "command_name": command_name,
+            "program_name": program_name,
+            "header_depth": header_depth,
+            "style": style,
+            "output": output,
+            "depth": depth,
+            "exclude": exclude,
+            "show_hidden": show_hidden,
+            "list_subcommands": list_subcommands,
+            "remove_ascii_art": remove_ascii_art,
+            "full_command_path": full_command_path,
+        },
+    )
+
+    try:
+        command = load_command(module_path, resolved["command_name"])
+    except LoadError as exc:
+        click.echo(f"Error: {exc}", err=True)
+        sys.exit(1)
+
+    markdown = generate_docs(
+        command,
+        program_name=resolved["program_name"],
+        header_depth=resolved["header_depth"],
+        style=resolved["style"],
+        depth=resolved["depth"],
+        exclude=resolved["exclude"],
+        show_hidden=resolved["show_hidden"],
+        list_subcommands=resolved["list_subcommands"],
+        remove_ascii_art=resolved["remove_ascii_art"],
+        full_command_path=resolved["full_command_path"],
+    )
+
+    if resolved["output"] is None:
+        click.echo(markdown, nl=False)
+        return
+
+    out_path = Path(resolved["output"])
+    if not out_path.parent.exists():
+        click.echo(f"Error: Output directory {out_path.parent!r} does not exist.", err=True)
+        sys.exit(1)
+
+    out_path.write_text(markdown, encoding="utf-8")

click_docs/config.py

@@ -0,0 +1,56 @@
+"""Configuration loading from pyproject.toml for click-docs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def find_config(start: Path | None = None) -> dict[str, Any]:
+    """
+    Searches for a 'pyproject.toml' file starting from a given directory and traversing up the directory tree.
+
+    If found, the configuration file is read and returned as a dictionary. If no configuration file is found, an
+    empty dictionary is returned.
+
+    Args:
+        start: Starting directory path to begin the search for 'pyproject.toml'. If None, the current
+            working directory is used.
+
+    Returns:
+        A dictionary containing the configuration data parsed from 'pyproject.toml'. Returns an empty
+        dictionary if no configuration file is located.
+    """
+    if start is None:
+        start = Path.cwd()
+
+    current = Path(start).resolve()
+    while True:
+        candidate = current / "pyproject.toml"
+        if candidate.is_file():
+            return _read_config(candidate)
+        parent = current.parent
+        if parent == current:
+            return {}
+        current = parent
+
+
+def _read_config(path: Path) -> dict[str, Any]:
+    """
+    Read the *[tool.click-docs]* section from a pyproject.toml file.
+
+    Args:
+        path: Path to the pyproject.toml file.
+
+    Returns:
+        Dict of *[tool.click-docs]* values, or empty dict if the section is absent.
+    """
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+
+    return data.get("tool", {}).get("click-docs", {})

click_docs/generator.py

@@ -0,0 +1,368 @@
+"""Generate Markdown documentation for a Click command."""
+
+from __future__ import annotations
+
+import inspect
+import re
+from contextlib import contextmanager, nullcontext
+from typing import Iterator
+
+import click
+
+
+def generate_docs(
+    command: click.BaseCommand,
+    program_name: str | None = None,
+    header_depth: int = 1,
+    style: str = "plain",
+    depth: int | None = None,
+    exclude: tuple[str, ...] | list[str] = (),
+    show_hidden: bool = False,
+    list_subcommands: bool = False,
+    remove_ascii_art: bool = False,
+    full_command_path: bool = False,
+) -> str:
+    """
+    Generate Markdown documentation for a Click command.
+
+    Args:
+        command: The Click command to document.
+        program_name: The display name used in the heading and usage line.
+            Defaults to the command's own ``name`` attribute.
+        header_depth: Markdown header level for the command title (1-6).
+        style: Options rendering style; ``"plain"`` (default) or ``"table"``.
+        depth: Maximum recursion depth. ``0`` = root only, ``None`` = unlimited.
+        exclude: Dotted command paths to skip (e.g. ``("root.admin.reset",)``).
+            The root command name is the first segment.
+        show_hidden: Include commands and options marked ``hidden=True``.
+        list_subcommands: Prepend a bulleted TOC of direct subcommands at the root.
+        remove_ascii_art: Strip ``\\b``-prefixed blocks (up to the next blank line).
+        full_command_path: Use the full command path in headers (e.g. ``cli admin``).
+
+    Returns:
+        A Markdown string ending with a single newline.
+    """
+    if program_name is None:
+        program_name = command.name or ""
+    exclude_set = frozenset(exclude)
+    # Collapse consecutive blank lines to a single blank line while iterating.
+    deduped: list[str] = []
+    for line in _recursively_make_command_docs(
+        command=command,
+        prog_name=program_name,
+        parent_ctx=None,
+        header_depth=header_depth,
+        style=style,
+        current_depth=0,
+        max_depth=depth,
+        exclude_set=exclude_set,
+        show_hidden=show_hidden,
+        list_subcommands=list_subcommands,
+        remove_ascii_art=remove_ascii_art,
+        full_command_path=full_command_path,
+        command_path=program_name,
+    ):
+        if line == "" and deduped and deduped[-1] == "":  # NOQA: PLC1901
+            continue
+        deduped.append(line)
+    return "\n".join(deduped) + "\n"
+
+
+def _recursively_make_command_docs(
+    command: click.BaseCommand,
+    prog_name: str,
+    parent_ctx: click.Context | None,
+    header_depth: int,
+    style: str,
+    current_depth: int,
+    max_depth: int | None,
+    exclude_set: frozenset[str],
+    show_hidden: bool,
+    list_subcommands: bool,
+    remove_ascii_art: bool,
+    full_command_path: bool,
+    command_path: str,
+) -> Iterator[str]:
+    """Yield Markdown lines for a command and its subcommands (depth-first)."""
+    if getattr(command, "hidden", False) and not show_hidden:
+        return
+
+    ctx = command.make_context(prog_name, [], parent=parent_ctx, resilient_parsing=True)
+
+    yield from _make_title(ctx, header_depth, full_command_path)
+    yield from _make_description(ctx, remove_ascii_art)
+    yield from _make_usage(ctx)
+    yield from _make_options(ctx, style, show_hidden)
+
+    if max_depth is not None and current_depth >= max_depth:
+        return
+
+    subcommands = _get_subcommands(command, ctx)
+    if not subcommands:
+        return
+
+    subcommands.sort(key=lambda cmd: cmd.name or "")
+
+    if list_subcommands and current_depth == 0:
+        yield ""
+        yield from _make_subcommands_toc(subcommands, ctx, show_hidden, full_command_path)
+
+    for subcmd in subcommands:
+        sub_name = subcmd.name or ""
+        sub_path = f"{command_path}.{sub_name}"
+        if sub_path in exclude_set:
+            continue
+        yield ""
+        yield from _recursively_make_command_docs(
+            command=subcmd,
+            prog_name=sub_name,
+            parent_ctx=ctx,
+            header_depth=header_depth + 1,
+            style=style,
+            current_depth=current_depth + 1,
+            max_depth=max_depth,
+            exclude_set=exclude_set,
+            show_hidden=show_hidden,
+            list_subcommands=list_subcommands,
+            remove_ascii_art=remove_ascii_art,
+            full_command_path=full_command_path,
+            command_path=sub_path,
+        )
+
+
+def _get_subcommands(command: click.BaseCommand, ctx: click.Context) -> list[click.BaseCommand]:
+    """Return direct subcommands of a group command."""
+    commands: dict = getattr(command, "commands", {})
+    if commands:
+        return list(commands.values())
+    if isinstance(command, click.Group):
+        result = []
+        for name in command.list_commands(ctx):
+            subcmd = command.get_command(ctx, name)
+            if subcmd is not None:
+                result.append(subcmd)
+        return result
+    return []
+
+
+def _slugify(text: str) -> str:
+    """Convert *text* to a GitHub-compatible anchor slug."""
+    text = text.lower()
+    text = re.sub(r"[^\w\s-]", "", text)
+    text = re.sub(r"[\s_]+", "-", text)
+    return text.strip("-")
+
+
+def _make_subcommands_toc(
+    subcommands: list[click.BaseCommand],
+    parent_ctx: click.Context,
+    show_hidden: bool,
+    full_command_path: bool,
+) -> Iterator[str]:
+    """Yield a bulleted TOC of direct subcommands with anchor links."""
+    yield "**Subcommands:**"
+    yield ""
+    for cmd in subcommands:
+        if getattr(cmd, "hidden", False) and not show_hidden:
+            continue
+        cmd_name = cmd.name or ""
+        header_text = f"{parent_ctx.command_path} {cmd_name}" if full_command_path else cmd_name
+        anchor = _slugify(header_text)
+        short_help = _get_short_help(cmd)
+        if short_help:
+            yield f"- [{cmd_name}](#{anchor}): {short_help}"
+        else:
+            yield f"- [{cmd_name}](#{anchor})"
+    yield ""
+
+
+def _get_short_help(command: click.BaseCommand) -> str:
+    """Return the first line of a command's help text (before \\f or \\n)."""
+    help_text = getattr(command, "help", None) or getattr(command, "short_help", None) or ""
+    help_text = inspect.cleandoc(help_text)
+    help_text = help_text.partition("\f")[0]
+    return help_text.splitlines()[0].strip() if help_text.strip() else ""
+
+
+def _make_title(
+    ctx: click.Context,
+    header_depth: int = 1,
+    full_command_path: bool = False,
+) -> Iterator[str]:
+    """Yield the command title as a Markdown heading at the given depth."""
+    text = ctx.command_path if full_command_path else ctx.info_name
+    yield f"{'#' * header_depth} {text}"
+    yield ""
+
+
+def _make_description(ctx: click.Context, remove_ascii_art: bool = False) -> Iterator[str]:
+    """Yield help text lines, truncating at ``\\f``.
+
+    Args:
+        ctx: The Click command context.
+        remove_ascii_art: Strip ``\\b``-prefixed ASCII art blocks (first ``\\b`` line
+            through the next blank line). Defaults to False.
+
+    Yields:
+        str: Lines from the command's help text.
+    """
+    help_text = ctx.command.help or ctx.command.short_help
+    if not help_text:
+        return
+    help_text = inspect.cleandoc(help_text)
+    help_text = help_text.partition("\f")[0]
+
+    if not remove_ascii_art:
+        yield from help_text.splitlines()
+        yield ""
+        return
+
+    # Strip the \b block: from first \b line through the next blank line.
+    in_ascii_art = False
+    for i, line in enumerate(help_text.splitlines()):
+        if not in_ascii_art:
+            if i == 0 and line.strip() == "\b":  # \b blocks only appear at the start of help text
+                in_ascii_art = True
+                continue
+            yield line
+        else:
+            if not line.strip():
+                in_ascii_art = False  # blank line ends the block; skip it
+            # else: skip this ascii art line
+    yield ""
+
+
+def _make_usage(ctx: click.Context) -> Iterator[str]:
+    """Yield a fenced-code usage block.
+
+    Args:
+        ctx: The Click command context.
+
+    Yields:
+        str: Markdown lines forming the ``**Usage:**`` fenced block.
+    """
+    formatter = ctx.make_formatter()
+    pieces = ctx.command.collect_usage_pieces(ctx)
+    formatter.write_usage(ctx.command_path, " ".join(pieces), prefix="")
+    usage = formatter.getvalue().strip()
+
+    yield "**Usage:**"
+    yield ""
+    yield "```text"
+    yield usage
+    yield "```"
+    yield ""
+
+
+def _make_options(ctx: click.Context, style: str = "plain", show_hidden: bool = False) -> Iterator[str]:
+    """Dispatch to the appropriate options renderer."""
+    if style == "table":
+        yield from _make_options_table(ctx, show_hidden)
+    else:
+        yield from _make_options_plain(ctx, show_hidden)
+
+
+@contextmanager
+def _unhide_options(ctx: click.Context) -> Iterator[None]:
+    """Temporarily unhide all hidden options on the command."""
+    hidden_opts = [p for p in ctx.command.params if isinstance(p, click.Option) and p.hidden]
+    try:
+        for opt in hidden_opts:
+            opt.hidden = False
+        yield
+    finally:
+        for opt in hidden_opts:
+            opt.hidden = True
+
+
+def _make_options_plain(ctx: click.Context, show_hidden: bool = False) -> Iterator[str]:
+    """Yield options as a fenced preformatted block from Click's own formatter.
+
+    Help text is truncated at ``\\f`` before being passed to the formatter.
+    """
+    ctx_mgr = _unhide_options(ctx) if show_hidden else nullcontext()
+    with ctx_mgr:
+        records = []
+        for param in ctx.command.get_params(ctx):
+            record = param.get_help_record(ctx)
+            if record is None:
+                continue
+            name, help_text = record
+            help_text = help_text.partition("\f")[0]
+            records.append((name, help_text))
+
+    if not records:
+        return
+
+    formatter = ctx.make_formatter()
+    with formatter.section("Options"):
+        formatter.write_dl(records)
+
+    option_lines = formatter.getvalue().splitlines()[1:]  # strip "Options:" header
+    if not option_lines:
+        return
+
+    yield "**Options:**"
+    yield ""
+    yield "```text"
+    yield from option_lines
+    yield "```"
+
+
+def _make_options_table(ctx: click.Context, show_hidden: bool = False) -> Iterator[str]:
+    """Yield options as a Markdown table with Name, Type, and Description columns."""
+    options = [
+        p
+        for p in ctx.command.params
+        if isinstance(p, click.Option) and not _is_help_option(p) and (show_hidden or not p.hidden)
+    ]
+    if not options:
+        return
+
+    yield "**Options:**"
+    yield ""
+    yield "| Name | Type | Description |"
+    yield "| --- | --- | --- |"
+    for opt in options:
+        name = " / ".join(opt.opts)
+        type_str = _format_param_type(opt.type)
+        help_text = (opt.help or "").partition("\f")[0].strip()
+        yield f"| {name} | {type_str} | {help_text} |"
+
+
+def _is_help_option(opt: click.Option) -> bool:
+    """Return True if *opt* is the auto-generated ``--help`` flag."""
+    return "--help" in opt.opts and opt.is_eager
+
+
+def _format_param_type(param_type: click.ParamType) -> str:
+    """Return a human-readable string for *param_type*, including constraints."""
+    if isinstance(param_type, click.Choice):
+        return f"one of: {', '.join(param_type.choices)}"
+    if isinstance(param_type, (click.IntRange, click.FloatRange)):
+        return _format_range(param_type)
+    if isinstance(param_type, click.DateTime):
+        return ", ".join(param_type.formats)
+    if isinstance(param_type, click.File):
+        return f"file ({param_type.mode})"
+    return param_type.name.upper()
+
+
+def _format_range(param_type: click.IntRange | click.FloatRange) -> str:
+    """Render an IntRange or FloatRange as a bounds expression like ``0<=x<=10``.
+
+    Args:
+        param_type: The range object with ``min``, ``max``, ``min_open``, and ``max_open``.
+
+    Returns:
+        A bounds string, e.g. ``0<=x``, ``x<=10``, or ``0<=x<=10``.
+    """
+    min_op = "<" if getattr(param_type, "min_open", False) else "<="
+    max_op = "<" if getattr(param_type, "max_open", False) else "<="
+    parts = []
+    if param_type.min is not None:
+        parts.append(f"{param_type.min}{min_op}")
+    parts.append("x")
+    if param_type.max is not None:
+        parts.append(f"{max_op}{param_type.max}")
+    return "".join(parts)

click_docs/loader.py

@@ -0,0 +1,83 @@
+"""Load a Click command object from a file system path."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from typing import Any
+
+import click
+
+
+class LoadError(Exception):
+    """Raised when a Click command cannot be loaded."""
+
+
+def load_command(module_path: str, command_name: str = "cli") -> click.BaseCommand:
+    """
+    Load a Click command from a Python file.
+
+    Args:
+        module_path: File system path to the Python module (absolute or relative to cwd).
+        command_name: Dotted attribute path on the module, e.g. ``cli`` or ``commands.root``.
+
+    Returns:
+        The resolved Click command object.
+
+    Raises:
+        LoadError: If the file does not exist, the attribute is missing, or the
+            resolved object is not a Click command.
+    """
+    path = Path(module_path)
+    if not path.exists():
+        raise LoadError(f"Module path {str(module_path)!r} does not exist.")
+
+    module = _load_module_from_path(path)
+    obj = _resolve_dotted_attr(module, command_name, module_path)
+
+    if not isinstance(obj, click.Command):
+        raise LoadError(
+            f"Attribute {command_name!r} in {str(module_path)!r} is not a Click command (got {type(obj).__name__!r})."
+        )
+
+    return obj
+
+
+def _load_module_from_path(path: Path) -> Any:
+    """Import a module from a file path and return the module object."""
+    resolved = path.resolve()
+    package_dir = resolved.parent
+    module_name = resolved.stem
+
+    # Insert the package directory so relative imports resolve correctly.
+    if str(package_dir) not in sys.path:
+        sys.path.insert(0, str(package_dir))
+
+    spec = importlib.util.spec_from_file_location(
+        module_name,
+        resolved,
+        submodule_search_locations=[str(package_dir)],
+    )
+    if spec is None or spec.loader is None:  # pragma: no cover
+        raise LoadError(f"Cannot load module from {str(path)!r}.")
+    module = importlib.util.module_from_spec(spec)
+    module.__package__ = module_name
+    sys.modules[module_name] = module
+    try:
+        spec.loader.exec_module(module)  # type: ignore[union-attr]
+    except Exception as exc:
+        sys.modules.pop(module_name, None)
+        raise LoadError(f"Error importing {str(path)!r}: {exc}") from exc
+    return module
+
+
+def _resolve_dotted_attr(obj: Any, dotted_path: str, source: str) -> Any:
+    """Walk a dotted attribute path on *obj*, raising LoadError if any segment is missing."""
+    parts = dotted_path.split(".")
+    current = obj
+    for part in parts:
+        if not hasattr(current, part):
+            raise LoadError(f"{source!r} has no attribute {part!r} (in path {dotted_path!r}).")
+        current = getattr(current, part)
+    return current

click_docs-0.2.0.dist-info/METADATA

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: click-docs
+Version: 0.2.0
+Summary: Generate Markdown documentation for your Click application
+Project-URL: Homepage, https://github.com/callowayproject/click-docs
+Project-URL: Documentation, https://callowayproject.github.io/click_docs
+Project-URL: Repository, https://github.com/callowayproject/click-docs
+Project-URL: Changelog, https://github.com/callowayproject/click-docs/CHANGELOG.md
+Author-email: Corey Oordt <coreyoordt@gmail.com>
+License: Copyright 2026 Corey Oordt
+        
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+        http://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+License-File: LICENSE
+Keywords: Markdown,click,documentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: markdown>=3.7
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# click-docs
+
+Generate Markdown documentation from your Click application — automatically, from source, with no manual editing required.
+
+[![PyPI version](https://img.shields.io/pypi/v/click-docs)](https://pypi.org/project/click-docs/)
+[![Python versions](https://img.shields.io/pypi/pyversions/click-docs)](https://pypi.org/project/click-docs/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/callowayproject/click-docs/test.yaml)](https://github.com/callowayproject/click-docs/actions)
+
+## About
+
+Click applications document themselves — click-docs reads that information and turns it into clean Markdown. Point it at a Python file, get a complete reference page: usage lines, options tables, nested subcommands, the works.
+
+It introspects Click objects directly and never executes your application, so there are no side effects and the output is always in sync with your source.
+
+## Features
+
+- **Zero-execution introspection** — reads Click objects, never runs your app
+- **Nested command support** — recursively documents subcommands with configurable depth
+- **Two option styles** — `plain` (preformatted text) or `table` (Markdown table)
+- **Configurable via `pyproject.toml`** — set defaults once in `[tool.click-docs]`
+- **Subcommand TOC** — optional bulleted table of contents at the top
+- **Filtering** — exclude specific commands, skip hidden commands, strip ASCII art blocks
+
+## Installation
+
+```console
+$ pip install click-docs
+```
+
+Or with `uv`:
+
+```console
+$ uv add click-docs
+```
+
+**Requirements:** Python 3.10+, Click 8.1+
+
+## Quick start
+
+Given a file `deployer.py` containing a Click application:
+
+```console
+$ click-docs deployer.py --program-name deployer --output docs/cli-reference.md
+```
+
+That's it. `docs/cli-reference.md` now contains the full Markdown reference for every command and option.
+
+## Common options
+
+| Option                 | Description                                   |
+|------------------------|-----------------------------------------------|
+| `--program-name TEXT`  | Display name in headings and usage lines      |
+| `--output FILE`        | Write to file instead of stdout               |
+| `--style plain\|table` | Options rendering style                       |
+| `--depth N`            | Max subcommand depth (0 = root only)          |
+| `--exclude PATH`       | Exclude a command by dotted path (repeatable) |
+| `--list-subcommands`   | Prepend a TOC of subcommands                  |
+| `--remove-ascii-art`   | Strip `\b`-prefixed ASCII art blocks          |
+
+Run `click-docs --help` for the full list.
+
+## Configure defaults in pyproject.toml
+
+Set project-wide defaults so you don't repeat flags on every run:
+
+```toml
+[tool.click-docs]
+program-name = "my-tool"
+style = "table"
+list-subcommands = true
+remove-ascii-art = true
+output = "docs/cli-reference.md"
+```
+
+## Documentation
+
+Full documentation, tutorials, and API reference: [callowayproject.github.io/click_docs](https://callowayproject.github.io/click_docs)
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Development setup
+
+```console
+$ git clone https://github.com/callowayproject/click-docs.git
+$ cd click-docs
+$ uv sync
+$ uv run pytest
+```
+
+## License
+
+click-docs is licensed under the Apache 2.0 license. See the [`LICENSE`](LICENSE) file for details.

click_docs-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+click_docs/__init__.py,sha256=MGLxrTAnHZo01cKz0t6Cjc-o6BxZlsw_om3N2YrM3xc,63
+click_docs/cli.py,sha256=o962sw5yWiQKztGaPYAX6AdQxi4U_VIPRJKUpuqm5dM,5521
+click_docs/config.py,sha256=jtD9cDQqqNbmRsCEPEM0f9lJbH0xVKwbjblLYXo-jhQ,1668
+click_docs/generator.py,sha256=fUzFXxKgKFXhkVjijOj4Pi7xijmK1fEwOqQB-uHzwqo,12399
+click_docs/loader.py,sha256=dgjaPOdQdSNFwD-gViKovjDxIexFmfwoG_wAeQ5pDeY,2746
+click_docs-0.2.0.dist-info/METADATA,sha256=UHgmR6Akh7PQAwfR9AFbMC6r6mQTHnQul37xePPIZ-k,5516
+click_docs-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+click_docs-0.2.0.dist-info/entry_points.txt,sha256=M1mdrvlvFX9mnytUDqpLRHI15ul-7GElRKt9cqmmuWs,50
+click_docs-0.2.0.dist-info/licenses/LICENSE,sha256=aHLo2QQ-TxK4ntWM6fKSlGu2LQFCxg3wEDYSLMqOvhc,548
+click_docs-0.2.0.dist-info/RECORD,,

click_docs-0.2.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

click_docs-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+click-docs = click_docs.cli:cli

click_docs-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Corey Oordt
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.