auto-api

Extract Python API docstrings and signatures into Markdown that is easy for AI agents to consume.

Usage

Install dependencies with uv:

uv sync

Extract docs from an installed module:

uv run auto-api extract --target json --functions dumps loads --output api_docs.md

Extract docs from a local package by adding a path to sys.path during resolution:

uv run auto-api extract --target ./src --functions my_package.module.function --output api_docs.md

Print Markdown to stdout by omitting --output:

uv run auto-api extract --target json --functions dumps loads

Output structure (body on):

# API Documentation

## List of functions

- json.dumps: Serialize ``obj`` to a JSON formatted ``str``.
- json.loads: Deserialize ``s`` (a ``str``, ``bytes`` or ``bytearray`` instance containing a JSON document) to a Python object.

## json.dumps

Source module: `json`

Signature:

```python
json.dumps(obj, *, skipkeys=False, ...)

Docstring:

Serialize ``obj`` to a JSON formatted ``str``.

Emit only the API reference (no per-entry body) with `--no-body`:

```bash
uv run auto-api extract --target json --no-body

Extract all public functions exposed by a target module:

uv run auto-api extract --target json

For installed modules, public functions come from __all__ when present, otherwise from names that do not start with _. Auto-discovery recurses into submodules and dedupes re-exports. Submodules whose names start with _ are skipped by default; pass --include-private-submodules to include them.

For local filesystem targets, auto-api walks importable modules under the path and extracts their public module-level functions:

uv run auto-api extract --target ./src --output api_docs.md

Notes

• The target module/package is imported, so import-time side effects may occur.
• Docstrings are preserved as cleaned text rather than parsed into a specific style.
• Unresolved APIs are included as error entries by default. Use --fail-on-error to return a non-zero exit code when any item fails.