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.
python -m pip install pyinc-docs
pyinc-docs build path/to/your_package --title "My Package API" --statsSOURCE 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" --statsThe 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" --statsWatch 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.modelsThe 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.
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.
- Getting started
- Tutorial package
- Command-line reference
- Static-analysis contract
- Compiler pipeline
- Cache and watch behavior
- Development and verification
- Release process
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 examplesGenerate this project's own API site with the installed command:
pyinc-docs build src/pyinc_docs -o site --title "pyinc-docs API" --statsLicensed under the Apache License, Version 2.0. See LICENSE.