Metadata-Version: 2.4
Name: pyinc-docs
Version: 0.1.0
Summary: A teaching-first incremental Python API documentation compiler.
Project-URL: Homepage, https://github.com/Brumbelow/pyinc-docs
Project-URL: Documentation, https://brumbelow.github.io/pyinc-docs/
Project-URL: Repository, https://github.com/Brumbelow/pyinc-docs
Project-URL: Issues, https://github.com/Brumbelow/pyinc-docs/issues
Author-email: Andrew Brumbelow <andrew.brumbelow@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: api-documentation,documentation-generator,incremental-computation,pyinc,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.11
Requires-Dist: pyinc<4,>=3.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# pyinc-docs

[![CI](https://github.com/Brumbelow/pyinc-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/Brumbelow/pyinc-docs/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/pyinc-docs)](https://pypi.org/project/pyinc-docs/)
[![Python versions](https://img.shields.io/pypi/pyversions/pyinc-docs)](https://pypi.org/project/pyinc-docs/)
[![License](https://img.shields.io/pypi/l/pyinc-docs)](https://pypi.org/project/pyinc-docs/)

`pyinc-docs` is a static Python API documentation compiler built as a
standalone consumer of [`pyinc`](https://github.com/Brumbelow/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

```console
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:

```console
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:

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

Preview the exact reconciliation without changing the site:

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

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

```console
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

```text
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](https://github.com/Brumbelow/pyinc-docs/blob/main/docs/getting-started.md)
- [Tutorial package](https://github.com/Brumbelow/pyinc-docs/blob/main/docs/tutorial.md)
- [Command-line reference](https://github.com/Brumbelow/pyinc-docs/blob/main/docs/cli.md)
- [Static-analysis contract](https://github.com/Brumbelow/pyinc-docs/blob/main/docs/static-analysis.md)
- [Compiler pipeline](https://github.com/Brumbelow/pyinc-docs/blob/main/docs/compiler-pipeline.md)
- [Cache and watch behavior](https://github.com/Brumbelow/pyinc-docs/blob/main/docs/cache-and-watch.md)
- [Development and verification](https://github.com/Brumbelow/pyinc-docs/blob/main/docs/development.md)
- [Release process](https://github.com/Brumbelow/pyinc-docs/blob/main/docs/release.md)

## Development

```console
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:

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

## License

Licensed under the Apache License, Version 2.0. See
[LICENSE](https://github.com/Brumbelow/pyinc-docs/blob/main/LICENSE).
