Metadata-Version: 2.4
Name: click-docs
Version: 0.3.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: rich-click>=1.8.4
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.
