Metadata-Version: 2.4
Name: pydoc2markdown
Version: 0.9.2
Summary: Convert Python docstrings to Markdown documentation.
Project-URL: Homepage, https://github.com/f1sherFM/PyDoc2Markdown
Project-URL: Repository, https://github.com/f1sherFM/PyDoc2Markdown
Project-URL: Issues, https://github.com/f1sherFM/PyDoc2Markdown/issues
Author-email: f1sherFM <f1sherFM@example.com>
License: MIT
License-File: LICENSE
Keywords: docstring,documentation,markdown,python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: docstring-parser>=0.15
Requires-Dist: jinja2>=3.1.0
Requires-Dist: tomli>=1.2.0; python_version < '3.11'
Provides-Extra: dev
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: watchdog>=3.0; extra == 'dev'
Provides-Extra: watch
Requires-Dist: watchdog>=3.0; extra == 'watch'
Description-Content-Type: text/markdown

# PyDoc2Markdown

[![CI](https://github.com/f1sherFM/PyDoc2Markdown/actions/workflows/ci.yml/badge.svg)](https://github.com/f1sherFM/PyDoc2Markdown/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/f1sherFM/PyDoc2Markdown/branch/main/graph/badge.svg)](https://codecov.io/gh/f1sherFM/PyDoc2Markdown)
[![PyPI](https://img.shields.io/pypi/v/pydoc2markdown)](https://pypi.org/project/pydoc2markdown/)
[![Python versions](https://img.shields.io/pypi/pyversions/pydoc2markdown)](https://pypi.org/project/pydoc2markdown/)
[![License](https://img.shields.io/pypi/l/pydoc2markdown)](https://github.com/f1sherFM/PyDoc2Markdown/blob/main/LICENSE)

> Generate clean Markdown API docs from Python docstrings without adopting a
> full documentation framework.

PyDoc2Markdown is a small CLI and library for projects that want useful API
docs to live in the repo, next to the code. Point it at a Python package and it
can generate plain `.md` files, a navigation-ready docs directory, a maintained
README API section, or a documentation coverage report for CI.

It is not trying to replace Sphinx for large documentation sites. It is for the
common middle ground: libraries, internal tools, services, and small packages
where Markdown output is enough and setup should stay boring.

## See It In One Command

```bash
pip install pydoc2markdown
pydoc2markdown --demo
```

That creates a tiny sample project, generates a browsable docs tree, and updates
the sample README with an API section. If you already have a package, start with:

```bash
pydoc2markdown src/my_package --recursive --doctor
pydoc2markdown src/my_package --recursive --nav --readme -o docs
```

You get normal Markdown files that are easy to inspect, commit, review, and
publish with GitHub, GitLab, MkDocs, or any static site setup.

![Generated docs showcase](docs/assets/readme-showcase.png)

## What It Gives You

- Plain `.md` files instead of a custom docs runtime
- A maintained API section inside `README.md`
- Navigation pages and package indexes for `docs/`
- Source links back to GitHub or another code host
- Output controls for public API, private members, attributes, returns, raises,
  and compact sections
- pdoc/mkdocstrings-style documented attributes for module constants, class
  fields, and instance attributes
- Optional docstring inheritance for subclass and override-heavy APIs
- Alias-aware detection for common Python patterns such as dataclasses, attrs
  classes, enums, protocols, ABCs, TypedDicts, and Pydantic models
- CI-friendly checks with `--check`, stale file cleanup with `--prune`, and docs
  coverage reporting with `--report`
- A read-only `--doctor` mode that summarizes docs readiness and suggests next
  commands before writing anything

## Project Health

Before adopting a docs tool, you should be able to inspect how it is built,
tested, released, and used. This repository keeps those signals visible:

- Published package: [pydoc2markdown on PyPI](https://pypi.org/project/pydoc2markdown/)
- Automated tests: [GitHub Actions CI](https://github.com/f1sherFM/PyDoc2Markdown/actions/workflows/ci.yml)
- Coverage reporting: [Codecov](https://codecov.io/gh/f1sherFM/PyDoc2Markdown)
- Release history: [CHANGELOG.md](CHANGELOG.md)
- Contributor workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
- Real generated output: [examples/sample_project/](examples/sample_project/)
- Issues and ideas: [GitHub Issues](https://github.com/f1sherFM/PyDoc2Markdown/issues)

## Before And After

Start with normal Python code and docstrings:

```python
def calculate_total(items: list[Product], discount: float = 0.0) -> float:
    """Calculate the discounted order total.

    Args:
        items: Products to include in the total.
        discount: Discount ratio between 0 and 1.

    Returns:
        Total price after discount.

    Raises:
        ValueError: If discount is outside the accepted range.
    """
```

PyDoc2Markdown turns it into Markdown with headings, parameter tables, return
types, and raised exceptions:

```markdown
### `calculate_total`

Calculate the discounted order total.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `list[Product]` | *required* | Products to include in the total. |
| `discount` | `float` | `0.0` | Discount ratio between 0 and 1. |

**Returns:** `float`
Total price after discount.

**Raises:**
- `ValueError`: If discount is outside the accepted range.
```

![Input to output example](docs/assets/readme-input-output.png)

## When To Use It

- Python libraries that want lightweight API docs in the repo
- Internal tools and services that keep docs next to the code
- Projects that want README API sections without copy-paste maintenance
- Teams that prefer plain Markdown over framework-specific output
- CI workflows that should fail when docs drift from the source

## Table of Contents

- [See It In One Command](#see-it-in-one-command)
- [What It Gives You](#what-it-gives-you)
- [Project Health](#project-health)
- [Before And After](#before-and-after)
- [When To Use It](#when-to-use-it)
- [Sample Project](#sample-project)
- [Why PyDoc2Markdown?](#why-pydoc2markdown)
- [Installation](#installation)
- [Doctor Diagnostics](#doctor-diagnostics)
- [Common Commands](#common-commands)
- [Recipes](#recipes)
- [Quick Start](#quick-start)
  - [CLI Usage](#cli-usage)
  - [Library Usage](#library-usage)
- [CLI Reference](#cli-reference)
- [Configuration](#configuration)
- [Module Filtering](#module-filtering)
- [Member Filtering](#member-filtering)
- [Source Links](#source-links)
- [Output Toggles](#output-toggles)
- [README API Sections](#readme-api-sections)
- [Navigation Docs Layout](#navigation-docs-layout)
- [CI Checks](#ci-checks)
- [Documentation Coverage Report](#documentation-coverage-report)
- [Prune Stale Docs](#prune-stale-docs)
- [Library API](#library-api)
- [Docstring Inheritance](#docstring-inheritance)
- [Documented Attributes](#documented-attributes)
- [Supported Docstring Formats](#supported-docstring-formats)
- [Example Output](#example-output)
- [Documentation](#documentation)
- [License](#license)

## Sample Project

The [sample project](examples/sample_project/) is a tiny shop package with
dataclasses, an enum, typed functions, properties, private helpers, and
Google-style docstrings. It shows what PyDoc2Markdown produces in a real repo
layout: source code, generated docs, and README sync side by side.

You can inspect the workflow here:

- [source code](examples/sample_project/src/shop_demo/)
- [generated docs index](examples/sample_project/docs/index.md)
- [README API section](examples/sample_project/README.md)

The generated docs layout looks like this:

```text
examples/sample_project/
|-- README.md
|-- src/shop_demo/
`-- docs/
    |-- index.md
    |-- shop_demo.md
    `-- api/shop_demo/
        |-- inventory.md
        `-- orders.md
```

You can also create the same kind of demo project locally:

```bash
pydoc2markdown --demo
```

By default this writes to `pydoc2markdown-demo/`. Use `--demo-output` to choose
another directory. Existing non-empty directories are not overwritten.

## Why PyDoc2Markdown?

Documentation generators like **Sphinx** are powerful, but they can be more
machinery than a small project needs: themes, `conf.py`, extensions, hosting
choices, and a documentation build pipeline. **pdoc** and **mkdocstrings** are
lighter, but they still pull you toward a broader docs stack.

PyDoc2Markdown keeps the output simple:

- **No `conf.py` required** - point it at source and generate Markdown
- **No framework lock-in** - the output is normal `.md`
- **Minimal dependencies** - Jinja2 and docstring-parser
- **Practical defaults** - useful output before writing config
- **Automation-friendly** - `--check`, `--prune`, `--report`, and library APIs

## Installation

Requirements:

- Python >= 3.10
- Runtime dependencies: [Jinja2](https://jinja.palletsprojects.com/) and
  [docstring-parser](https://github.com/rr-/docstring-parser)
- Optional: [watchdog](https://github.com/argoslabs/python-watchdog) for
  `--watch` mode

```bash
# Base installation
pip install pydoc2markdown

# With file watcher support
pip install pydoc2markdown[watch]
```

## Doctor Diagnostics

Use `--doctor` when you want PyDoc2Markdown to inspect a project before writing
any generated files:

```bash
pydoc2markdown src/my_package --recursive --doctor
```

The doctor report summarizes what PyDoc2Markdown sees:

- modules, classes, functions, and `__all__` exports
- docstring and parameter-description readiness
- whether the README target exists
- whether `[tool.pydoc2markdown]` config is present
- recommended next commands for docs, README sync, CI checks, and coverage

Example output:

```text
PyDoc2Markdown Doctor

Scanned:
- Source: src/my_package
- Recursive: yes
- Modules: 12
- Classes: 18
- Functions: 43
- __all__ exports: 7

Docs readiness:
- Module docstrings: 10/12 (83.3%)
- Class docstrings: 17/18 (94.4%)
- Function docstrings: 39/43 (90.7%)
- Public API exports: 7/7 (100.0%)
- Parameter descriptions: 82/96 (85.4%)
- Overall: 89.2%

Recommended commands:
- Generate navigation docs:
  pydoc2markdown src/my_package --recursive --nav -o docs
- Keep README API section in sync:
  pydoc2markdown src/my_package --recursive --readme --readme-path README.md
```

## Common Commands

Start with the command that matches how you want to publish docs:

| Goal | Command |
|------|---------|
| Inspect docs readiness first | `pydoc2markdown src/my_package --recursive --doctor` |
| Generate module docs | `pydoc2markdown src/my_package --recursive -o docs` |
| Generate a docs index and API pages | `pydoc2markdown src/my_package --recursive --nav -o docs` |
| Update the API section in README.md | `pydoc2markdown src/my_package --recursive --readme` |
| Use a custom README section title | `pydoc2markdown src/my_package --recursive --readme --readme-title "Developer API"` |
| Skip private/internal modules | `pydoc2markdown src/my_package --recursive --exclude "tests/*,*/internal/*,*_private.py"` |
| Add GitHub source links | `pydoc2markdown src/my_package --recursive --source-repo user/repo -o docs` |
| Generate a compact docs layout | `pydoc2markdown src/my_package --recursive --compact-sections -o docs` |
| Hide returns and raises in generated docs | `pydoc2markdown src/my_package --recursive --no-show-returns --no-show-raises -o docs` |
| Keep docs focused on exported API | `pydoc2markdown src/my_package --recursive --public-only -o docs` |
| Reuse base class and override docs | `pydoc2markdown src/my_package --recursive --inherit-docstrings -o docs` |
| Include private helpers and dunder methods | `pydoc2markdown src/my_package --recursive --show-private-members --show-dunder-members -o docs` |
| Include only selected members by name | `pydoc2markdown src/my_package --recursive --member-include "Client,Client.run,public_*" -o docs` |
| Exclude noisy helpers by name | `pydoc2markdown src/my_package --recursive --member-exclude "_debug,Client.helper,*.backup" -o docs` |
| Check generated docs in CI | `pydoc2markdown src/my_package --recursive --nav --readme --check -o docs` |
| Print a documentation coverage report | `pydoc2markdown src/my_package --recursive --report` |
| Fail CI when selected report findings exist | `pydoc2markdown src/my_package --recursive --report --fail-on modules,params` |
| Fail CI when overall report coverage drops below a target | `pydoc2markdown src/my_package --recursive --report --fail-under 95` |
| Export the report as JSON | `pydoc2markdown src/my_package --recursive --report --report-format json` |
| Save the report as a CI artifact | `pydoc2markdown src/my_package --recursive --report --report-format json --report-output reports/doc-coverage.json` |
| Print only the report summary in CI logs | `pydoc2markdown src/my_package --recursive --report --report-summary-only` |
| Focus the report on selected categories | `pydoc2markdown src/my_package --recursive --report --report-categories modules,params` |
| Preview stale generated docs cleanup | `pydoc2markdown src/my_package --recursive --prune --dry-run -o docs` |
| Remove stale generated docs | `pydoc2markdown src/my_package --recursive --prune -o docs` |
| Generate one combined Markdown file | `pydoc2markdown src/my_package --recursive --single-file -o docs/api.md` |
| Watch source files while editing | `pydoc2markdown src/my_package --recursive --watch -o docs` |
| Create default pyproject config | `pydoc2markdown --init` |
| Create a local demo project | `pydoc2markdown --demo` |

Use `--theme minimal` for shorter output, or `--template path/to/template.md.j2`
when a project needs custom Markdown.

## Recipes

Here are a few practical ways teams tend to use PyDoc2Markdown.

### Keep API docs in `docs/`

Generate a navigation-ready docs tree for a package:

```bash
pydoc2markdown src/my_package --recursive --nav -o docs
```

This works well when you want browsable Markdown pages in the repository,
MkDocs, or another lightweight docs site.

### Keep a README API block in sync

Update a generated API section without touching the rest of the README:

```bash
pydoc2markdown src/my_package --recursive --readme --readme-path README.md
```

This is a good fit for small libraries that want usage notes and API reference
in one file.

Use `--readme-mode detailed` when you want a richer embedded API section:

```bash
pydoc2markdown src/my_package --recursive --readme --readme-mode detailed
```

### Gate docs in CI

Fail CI when generated docs are missing, stale, or no longer match the source
tree:

```bash
pydoc2markdown src/my_package --recursive --nav --readme --check -o docs
```

Pair this with `--prune` in local development to keep generated docs tidy after
renames and deletions.

### Generate docs only for the public surface

Focus on selected packages and skip internal modules:

```bash
pydoc2markdown src/my_package --recursive \
  --include "api/*,models/*" \
  --exclude "*/internal/*,*_test.py" \
  -o docs
```

This is useful when your source tree is larger than the documentation surface
you actually want to publish.

## Quick Start

### CLI Usage

```bash
# Generate docs for a single file
pydoc2markdown my_module.py -o docs

# Recursively process a package
pydoc2markdown src/my_package --recursive -o docs

# Skip internal and test modules
pydoc2markdown src/my_package --recursive --exclude "tests/*,*/internal/*,*_test.py" -o docs

# Generate a navigation-first docs layout
pydoc2markdown src/my_package --recursive --nav -o docs

# Inspect docs readiness without writing files
pydoc2markdown src/my_package --recursive --doctor

# Add GitHub source links next to documented objects
pydoc2markdown src/my_package --recursive --source-repo user/repo -o docs

# Hide the module TOC and use a tighter built-in layout
pydoc2markdown src/my_package --recursive --no-show-toc --compact-sections -o docs

# Trim output sections you do not want in published docs
pydoc2markdown src/my_package --recursive \
  --no-show-public-api \
  --no-show-attributes \
  --no-show-returns \
  --no-show-raises \
  -o docs

# Check whether generated docs are current without writing files
pydoc2markdown src/my_package --recursive --nav --check -o docs

# Print a documentation coverage report
pydoc2markdown src/my_package --recursive --report

# Fail when undocumented modules or missing param docs are found
pydoc2markdown src/my_package --recursive --report --fail-on modules,params

# Fail when overall coverage falls below a target percentage
pydoc2markdown src/my_package --recursive --report --fail-under 95

# Keep CI logs compact while still showing totals and counts
pydoc2markdown src/my_package --recursive --report --report-summary-only

# Focus the report on the categories you care about
pydoc2markdown src/my_package --recursive --report --report-categories modules,params

# Emit machine-readable JSON
pydoc2markdown src/my_package --recursive --report --report-format json

# Save the report as a CI artifact while still printing it to stdout
pydoc2markdown src/my_package --recursive --report \
  --report-format json \
  --report-output reports/doc-coverage.json

# Preview stale generated Markdown files before removing them
pydoc2markdown src/my_package --recursive --prune --dry-run -o docs

# Remove stale generated Markdown files tracked by PyDoc2Markdown
pydoc2markdown src/my_package --recursive --prune -o docs

# Initialize default configuration in pyproject.toml
pydoc2markdown --init
```

### Library Usage

```python
from pathlib import Path
from pydoc2markdown import DocstringParser, MarkdownGenerator, OutputOptions

parser = DocstringParser()
modules = parser.parse(Path("src/my_package"), recursive=True)

generator = MarkdownGenerator(
    theme="default",
    output_options=OutputOptions(show_toc=False, compact_sections=True),
)
generator.generate(modules, output_dir=Path("docs"))
```

## CLI Reference

| Flag | Default | Description |
|------|---------|-------------|
| `source` | *(required unless `--init` is used)* | Path to a Python file or directory to process |
| `--init` | `False` | Create or update `[tool.pydoc2markdown]` in `pyproject.toml` |
| `-o`, `--output` | `docs` / value from `pyproject.toml` | Output directory (or file path when `--single-file` is used) |
| `--recursive` | `False` / value from `pyproject.toml` | Recursively process subdirectories |
| `--include` | `None` | Comma-separated glob patterns for files to include |
| `--exclude` | `None` | Comma-separated glob patterns for files to exclude |
| `--theme` | `default` / value from `pyproject.toml` | Built-in theme: `default` (detailed) or `minimal` |
| `--template` | `None` | Path to a custom Jinja2 template for Markdown generation |
| `--show-toc`, `--no-show-toc` | `True` / value from `pyproject.toml` | Show or hide the module table of contents in built-in output |
| `--show-source-links`, `--no-show-source-links` | `True` / value from `pyproject.toml` | Show or hide built-in source links |
| `--compact-sections`, `--no-compact-sections` | `False` / value from `pyproject.toml` | Use a tighter built-in Markdown layout |
| `--show-class-metadata`, `--no-show-class-metadata` | `True` / value from `pyproject.toml` | Show or hide built-in class metadata like bases and status markers |
| `--show-public-api`, `--no-show-public-api` | `True` / value from `pyproject.toml` | Show or hide the Public API block derived from `__all__` |
| `--show-attributes`, `--no-show-attributes` | `True` / value from `pyproject.toml` | Show or hide built-in attribute and model field tables |
| `--show-returns`, `--no-show-returns` | `True` / value from `pyproject.toml` | Show or hide Returns sections in built-in output |
| `--show-raises`, `--no-show-raises` | `True` / value from `pyproject.toml` | Show or hide Raises sections in built-in output |
| `--show-private-members`, `--no-show-private-members` | `False` / value from `pyproject.toml` | Show or hide private names such as `_helper` and `_debug` |
| `--show-dunder-members`, `--no-show-dunder-members` | `False` / value from `pyproject.toml` | Show or hide dunder members such as `__repr__` |
| `--public-only`, `--no-public-only` | `False` / value from `pyproject.toml` | When `__all__` exists, keep docs focused on that exported top-level API |
| `--inherit-docstrings`, `--no-inherit-docstrings` | `False` / value from `pyproject.toml` | Fill missing subclass and override method docs from parsed base classes |
| `--member-include` | `None` / value from `pyproject.toml` | Comma-separated glob patterns for member names to include |
| `--member-exclude` | `None` / value from `pyproject.toml` | Comma-separated glob patterns for member names to exclude |
| `--single-file` | `False` | Generate a single combined Markdown file; `--output` must be a `.md` or `.markdown` file path |
| `--check` | `False` | Check whether generated docs are up to date without writing files |
| `--prune` | `False` | Remove stale generated Markdown files tracked by PyDoc2Markdown |
| `--dry-run` | `False` | Preview `--prune` results without deleting files |
| `--report` | `False` | Print a documentation coverage report instead of generating Markdown files |
| `--report-categories` | `None` | Comma-separated report categories to include in output: `modules`, `classes`, `functions`, `public_api`, `params` |
| `--report-format` | `text` | Output format for `--report`: `text` or `json` |
| `--fail-on` | `None` | Comma-separated report categories that should return exit code `1`: `modules`, `classes`, `functions`, `public_api`, `params`, or `any` |
| `--fail-under` | `None` | Return exit code `1` when overall report coverage falls below this percentage |
| `--report-output` | `None` | Also write the report output to a file |
| `--report-summary-only` | `False` | Print report totals and counts without listing every finding |
| `--doctor` | `False` | Inspect docs readiness and recommended commands without writing files |
| `--readme` | `False` | Create or update an API reference section in README.md |
| `--readme-path` | `README.md` | Path to the README file updated by `--readme` |
| `--readme-mode` | `summary` / value from `pyproject.toml` | README rendering mode: `summary` or `detailed` |
| `--readme-title` | `API Reference` / value from `pyproject.toml` | Section title used for generated README content |
| `--nav` | `False` | Generate a navigation-first docs layout with API pages under `api/` |
| `--api-dir` | `api` | Directory for API pages when `--nav` is used |
| `--source-link` | `None` | URL template for source links, using `{path}`, `{file}`, and `{line}` |
| `--source-repo` | `None` | GitHub repository shorthand for source links, for example `user/repo` |
| `--watch` | `False` | Watch source files and regenerate docs on change |
| `--demo` | `False` | Create a small demo project and generate docs for it |
| `--demo-output` | `pydoc2markdown-demo` | Directory created by `--demo` |
| `-v`, `--verbose` | `0` | Increase verbosity (`-v` = INFO, `-vv` = DEBUG) |
| `--version` | - | Show version and exit |

**Configuration priority:** CLI flags > `[tool.pydoc2markdown]` in `pyproject.toml` > built-in defaults.

## Configuration

You can initialize default configuration with:

```bash
pydoc2markdown --init
```

This creates or appends a `[tool.pydoc2markdown]` section in `pyproject.toml`.
If the section already exists, it is left unchanged.

You can also set default values manually in your `pyproject.toml`:

```toml
[tool.pydoc2markdown]
output = "docs"
theme = "default"
recursive = true
show_toc = true
show_source_links = true
compact_sections = false
show_class_metadata = true
show_public_api = true
show_attributes = true
show_returns = true
show_raises = true
show_private_members = false
show_dunder_members = false
public_only = false
inherit_docstrings = false
member_include = ["Client", "Client.run", "public_*"]
member_exclude = ["Client.helper", "_debug"]
readme_mode = "summary"
readme_title = "API Reference"
```

Any values set here serve as defaults and can be overridden by CLI flags.

## Module Filtering

Use `--include` and `--exclude` with `--recursive` to control which Python files
are documented:

```bash
pydoc2markdown src/my_package --recursive --exclude "tests/*,*/internal/*,*_private.py"
```

Patterns use standard shell-style globs and are matched against paths relative
to the scanned source root. Patterns without a directory separator also match
file names in any package directory, so `conftest.py` or `*_test.py` work as
convenient basename filters.

When both flags are used, PyDoc2Markdown applies `--include` first and then
removes anything matched by `--exclude`:

```bash
pydoc2markdown src/my_package --recursive --include "api/*,core/*" --exclude "*/generated.py"
```

## Member Filtering

Use member filtering when you want to narrow documentation inside each module,
not just choose which files are parsed.

`--public-only` is the highest-signal option for library projects. When a
module defines `__all__`, PyDoc2Markdown keeps the exported top-level classes
and functions in docs, README summaries, single-file output, navigation docs,
and `--report`:

```bash
pydoc2markdown src/my_package --recursive --public-only -o docs
```

Private names such as `_helper` and `_debug` are hidden by default. Dunder
members such as `__repr__` are hidden by default as well. If you want to expose
those internals in generated docs, opt in explicitly:

```bash
pydoc2markdown src/my_package --recursive \
  --show-private-members \
  --show-dunder-members \
  -o docs
```

These controls affect:

- generated module docs
- navigation docs
- single-file output
- README API sections
- `--report`

That keeps the visible docs surface and the reported coverage surface aligned.
For class docs, the same filtering rules also apply to attribute tables and
Pydantic field tables.

When you need more precision, use `--member-include` and `--member-exclude`.
Patterns are matched against a few useful forms for the same object:

- bare names like `helper` or `Widget`
- class-qualified names like `Client.run`
- module-qualified names like `my_pkg.client.helper`
- fully qualified method names like `my_pkg.client.Client.run`

For example:

```bash
pydoc2markdown src/my_package --recursive \
  --member-include "Client,Client.run,public_*" \
  --member-exclude "Client.helper,_debug,*.backup" \
  -o docs
```

This is applied after file-level include/exclude and alongside `public_only`,
private-member, and dunder-member controls.

## Source Links

Use `--source-repo` to add GitHub source links next to generated class,
function, and method headings:

```bash
pydoc2markdown src/my_package --recursive --source-repo user/repo -o docs
```

This expands to a GitHub URL template using the `main` branch:

```text
https://github.com/user/repo/blob/main/{path}#L{line}
```

For GitLab, another branch, or a custom host, pass the full template with
`--source-link`:

```bash
pydoc2markdown src/my_package --recursive \
  --source-link "https://gitlab.com/user/repo/-/blob/develop/{path}#L{line}" \
  -o docs
```

Available template variables are `{path}` for the source-root-relative Python
file path, `{file}` for the filename, and `{line}` for the 1-indexed definition
line.

## Output Toggles

PyDoc2Markdown's built-in renderer can be trimmed without writing a custom
template. You can set these toggles per run or keep them in
`[tool.pydoc2markdown]`.

- `show_toc`
- `show_source_links`
- `compact_sections`
- `show_class_metadata`
- `show_public_api`
- `show_attributes`
- `show_returns`
- `show_raises`
- `show_private_members`
- `show_dunder_members`
- `public_only`
- `member_include`
- `member_exclude`

For example, this keeps parameter tables but removes Public API, Returns, and
Raises blocks from generated docs:

```bash
pydoc2markdown src/my_package --recursive \
  --no-show-public-api \
  --no-show-returns \
  --no-show-raises \
  -o docs
```

## README API Sections

Use `--readme` to create or update a generated API reference in your README:

```bash
pydoc2markdown src/my_package --recursive --readme
```

By default, PyDoc2Markdown updates `README.md`. Use `--readme-path` to target a
different file:

```bash
pydoc2markdown src/my_package --recursive --readme --readme-path docs/index.md
```

`summary` is the default README mode and is optimized for a lightweight module
overview. It now includes short module summaries, compact counts, and one-line
class/function previews. When a module defines `__all__`, the summary also
prioritizes those exported names as the README-facing public API. When README
generation runs alongside docs generation, module headings also link back to
the generated Markdown pages automatically. For projects with multiple package
groups, summary mode also adds lightweight package sections and uses package
`__init__` docstrings as short intros when available. It also adds an overview
line and quick links for the generated module set. Those quick links point to
generated docs when available, and otherwise fall back to internal README
anchors. Use
`--readme-mode detailed` for a richer embedded API section that reuses the
built-in Markdown renderer without per-module TOCs.

Use `--readme-title` when the generated section should appear under a different
heading:

```bash
pydoc2markdown src/my_package --recursive --readme --readme-title "Developer API"
```

When the file already contains PyDoc2Markdown markers, only the generated block
between the markers is replaced:

```markdown
## API Reference

<!-- pydoc2markdown:start -->
<!-- pydoc2markdown:end -->
```

If the markers are missing, a new `## API Reference` section is appended. If the
README does not exist, it is created.

## Navigation Docs Layout

Use `--nav` when you want a docs directory that is ready to browse from a single
entrypoint:

```bash
pydoc2markdown src/my_package --recursive --nav -o docs
```

This creates a layout like:

```text
docs/
|-- index.md
|-- modules.md
`-- api/
    |-- package.md
    `-- utils.md
```

The root `index.md` links to package landing pages and every generated API page.
Use `--api-dir` to change where module pages are written:

```bash
pydoc2markdown src/my_package --recursive --nav --api-dir reference -o docs
```

## CI Checks

Use `--check` in CI to fail when generated documentation is missing or stale:

```bash
pydoc2markdown src/my_package --recursive --nav --readme --check -o docs
```

The command compares the files PyDoc2Markdown would generate with the files
already on disk. It exits with `0` when docs are current and `1` when any
generated output needs to be updated. It does not write files in check mode.

`--check` works with normal multi-file output, `--nav`, `--single-file`, and
README API sections. It cannot be combined with `--watch`.

## Documentation Coverage Report

Use `--report` when you want a quick documentation audit without writing any
Markdown files:

```bash
pydoc2markdown src/my_package --recursive --report
```

The report prints totals plus findings for:

- modules without docstrings
- classes without docstrings
- functions without docstrings
- undocumented `__all__` exports
- parameters missing descriptions

The text report also includes an overall coverage percentage and per-category
coverage breakdown so you can see where gaps are concentrated.

By default, `--report` is analysis-only and exits successfully when the report
is produced. Use `--fail-on` when you want selected findings to fail CI:

```bash
pydoc2markdown src/my_package --recursive --report --fail-on modules,params
```

Use `--fail-on any` to fail on any non-zero finding category.

Use `--fail-under` when you want to enforce a minimum overall coverage target:

```bash
pydoc2markdown src/my_package --recursive --report --fail-under 95
```

Use `--report-summary-only` when you want compact CI logs that still show
coverage totals and category counts:

```bash
pydoc2markdown src/my_package --recursive --report --report-summary-only
```

Use `--report-categories` when you want to focus the report on a smaller slice
of documentation debt:

```bash
pydoc2markdown src/my_package --recursive --report --report-categories modules,params
```

For automation, JSON output is also available:

```bash
pydoc2markdown src/my_package --recursive --report --report-format json
```

To keep the report as a build artifact, add `--report-output`:

```bash
pydoc2markdown src/my_package --recursive --report \
  --report-format json \
  --report-output reports/doc-coverage.json
```

## Prune Stale Docs

Use `--prune` to remove stale generated Markdown files that were tracked by
PyDoc2Markdown in a previous run but are no longer expected for the current
source tree:

```bash
pydoc2markdown src/my_package --recursive --prune -o docs
```

To preview the cleanup first, add `--dry-run`:

```bash
pydoc2markdown src/my_package --recursive --prune --dry-run -o docs
```

`--prune` only affects generated Markdown files recorded in the PyDoc2Markdown
manifest. It does not try to delete unrelated hand-written Markdown files that
may live in the same docs directory.

## Library API

### DocstringParser

```python
from pathlib import Path
from pydoc2markdown import DocstringParser

parser = DocstringParser()
modules = parser.parse(Path("src/my_package"), recursive=True)
```

### MarkdownGenerator

```python
from pathlib import Path
from pydoc2markdown import DocstringParser, MarkdownGenerator, OutputOptions

# Parse modules
parser = DocstringParser()
modules = parser.parse(Path("src/my_package"), recursive=True)

# Default theme, separate files
gen = MarkdownGenerator(theme="default")
gen.generate(modules, output_dir=Path("docs"))

# Built-in output toggles
gen_tuned = MarkdownGenerator(
    theme="default",
    output_options=OutputOptions(
        show_toc=False,
        compact_sections=True,
        public_only=True,
    ),
)
gen_tuned.generate(modules, output_dir=Path("docs_compact"))

# Minimal theme
gen_min = MarkdownGenerator(theme="minimal")
gen_min.generate(modules, output_dir=Path("docs_minimal"))

# Custom template
gen_tmpl = MarkdownGenerator(template_path=Path("my_template.md.j2"))
gen_tmpl.generate(modules, output_dir=Path("docs_custom"))

# Single combined file
gen.generate_single_file(modules, output_path=Path("docs/README.md"))

# README API section
gen.update_readme(modules, readme_path=Path("README.md"))

# Navigation docs layout
gen.generate_navigation(modules, output_dir=Path("docs"))

# Markdown string for a single module
md_string = gen.generate_string(modules[0])
```

## Docstring Inheritance

Use `--inherit-docstrings` when subclass-heavy code would otherwise repeat the
same class or method descriptions:

```bash
pydoc2markdown src/my_package --recursive --inherit-docstrings -o docs
```

When enabled, PyDoc2Markdown fills missing subclass docstrings and override
method docs from parsed base classes. Explicit subclass docstrings are kept as
written. Override methods can also inherit missing return descriptions, raises
sections, and parameter descriptions by matching parameter names.

The same behavior is available from the library API:

```python
parser = DocstringParser(inherit_docstrings=True)
modules = parser.parse(Path("src/my_package"), recursive=True)
```

## Documented Attributes

PyDoc2Markdown recognizes the common pdoc/mkdocstrings-style pattern where a
string literal immediately follows an assignment. This works for module
constants, class fields, dataclass fields, Pydantic fields, and instance
attributes assigned in `__init__`:

```python
DEFAULT_TIMEOUT: float = 30.0
"""Default request timeout in seconds."""


class Client:
    """HTTP client."""

    default_retries: int = 3
    """Default retry count."""

    def __init__(self, token: str) -> None:
        self.token: str = token
        """Authentication token."""
```

Those descriptions are rendered as Markdown attribute sections and are also
used by README summaries and `__all__` public API reporting.

Class metadata detection is import-alias-aware, so common patterns like
`import dataclasses as dc`, `import attrs`, `from enum import Enum as PyEnum`,
and `from pydantic import BaseModel as Model` still render the expected
dataclass, attrs, enum, protocol, abstract, TypedDict, and Pydantic labels.

## Supported Docstring Formats

PyDoc2Markdown uses [docstring-parser](https://github.com/rr-/docstring-parser) and supports common structured docstring sections:

| Style | Support | Notes |
|-------|---------|-------|
| **Google** | Full | Args, Returns, Raises, Attributes, Examples |
| **NumPy** | Full | Parameters, Returns, Raises, Attributes, Examples |
| **reStructuredText (reST)** | Basic | Field-style metadata via `docstring-parser`, including `:param:`, `:returns:`, and `:raises:` |

## Example Output

Given this source file:

```python
from pydantic import BaseModel, Field


class User(BaseModel):
    """A user in the system."""

    id: int = Field(description="Unique identifier")
    email: str = Field(default="", description="Email address")
    is_active: bool = True


class UserService:
    """Service for managing users."""

    def get_user(self, user_id: int) -> User:
        """Fetch a user by ID.

        Args:
            user_id: The user's unique identifier.

        Returns:
            The requested User instance.

        Raises:
            ValueError: If the user does not exist.
        """
        ...
```

Running `pydoc2markdown src/users.py -o docs` produces:

```markdown
# users

## Table of Contents

- [Classes](#classes)
  - [`User`](#user)
  - [`UserService`](#userservice)

## Classes

### `User` *(Pydantic)*

A user in the system.

#### Pydantic Fields

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `id` | `int` | *required* | Unique identifier |
| `email` | `str` | `""` | Email address |
| `is_active` | `bool` | `True` | - |

### `UserService`

Service for managing users.

#### Methods

##### `get_user`

Fetch a user by ID.

**Parameters:**

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `user_id` | `int` | *required* | The user's unique identifier. |

**Returns:** `User`

**Raises:**

- `ValueError`: If the user does not exist.
```

For a complete small project, see [examples/sample_project/](examples/sample_project/).
It includes source code, a generated README API section, and a navigation-first
docs layout generated by PyDoc2Markdown. You can also see pre-built
documentation for this repository in [examples/docs/](examples/docs/).

## Documentation

- [Contributing Guide](CONTRIBUTING.md)
- [Project Structure](PROJECT_STRUCTURE.md)

## License

MIT License - see [LICENSE](LICENSE) for details.
