pyinc-docs

pyinc-docs is a static Python API documentation compiler built as a standalone consumer of pyinc. It turns a regular Python package into a deterministic, searchable HTML site without importing or executing the package being documented.

The compiler is deliberately small enough to teach from. Its query graph makes each step visible: discover files, decode source, extract public API, link local annotations, render artifacts, and reconcile the desired site. Repeated builds reuse unchanged work, backdate semantically unchanged analysis, and repair tampered generated files.

pyinc-docs supports Python 3.11 through 3.14 and has one runtime dependency: pyinc>=3.0,<4.

Quick start

python -m pip install pyinc-docs
pyinc-docs build path/to/your_package --title "My Package API" --stats

SOURCE is the package directory itself: it must contain __init__.py. From a source checkout, build the included tutorial package with:

pyinc-docs build examples/tutorial/acme_widgets --title "Acme Widgets API" --stats

The default site is written to site/ and durable query state to .pyinc-docs/. A successful build creates this public layout:

site/
├── assets/
│   ├── search.js
│   └── style.css
├── modules/
│   └── <module>.html
├── index.html
└── symbols.json

Preview the exact reconciliation without changing the site:

pyinc-docs plan examples/tutorial/acme_widgets --title "Acme Widgets API" --stats

Watch a package during development or inspect why one module was recomputed:

pyinc-docs watch examples/tutorial/acme_widgets --interval-ms 250 --debounce-ms 150
pyinc-docs explain examples/tutorial/acme_widgets acme_widgets.models

Static API rules

The source must be one regular package directory with an __init__.py file. Regular subpackages are recursive; namespace-package gaps, duplicate module identities, source-tree symlinks, and unsafe paths are rejected.

A module's public API comes from one static __all__ list or tuple of strings. Without one, public top-level functions and classes are documented. Dynamic __all__ assignments produce a warning and fall back to that convention. Module, function, class, constructor, public method, static method, class method, and property documentation is extracted from source. Docstrings are escaped plain text rather than interpreted as Markdown or reStructuredText.

Annotation links resolve within a module and across one explicit local import, including imports guarded by TYPE_CHECKING. Explicit local re-exports named by __all__ are supported. Wildcard imports, recursive export chains, external annotations, and unresolved names remain unlinked.

Compilation is transactional from the user's point of view. Encoding errors, syntax errors, unsafe paths, and output collisions stop reconciliation, leaving the last valid site and checkpoint untouched.

Commands

pyinc-docs build SOURCE [-o site] [--state-dir .pyinc-docs] [--title TITLE] [--stats]
pyinc-docs plan SOURCE [-o site] [--state-dir .pyinc-docs] [--title TITLE] [--stats]
pyinc-docs watch SOURCE [-o site] [--state-dir .pyinc-docs] [--title TITLE]
                 [--interval-ms 250] [--debounce-ms 150] [--stats]
pyinc-docs explain SOURCE MODULE [--state-dir .pyinc-docs] [--title TITLE]
pyinc-docs cache clean [--state-dir .pyinc-docs]
pyinc-docs --version

Successful commands return 0, compiler and operational failures return 1, and invalid command-line usage returns 2.

Documentation

• Getting started
• Tutorial package
• Command-line reference
• Static-analysis contract
• Compiler pipeline
• Cache and watch behavior
• Development and verification
• Release process

Development

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e '.[dev]'
pytest
python -m mypy
python -m ruff check src tests examples
python -m ruff format --check src tests examples

Generate this project's own API site with the installed command:

pyinc-docs build src/pyinc_docs -o site --title "pyinc-docs API" --stats

License

Licensed under the Apache License, Version 2.0. See LICENSE.