README.md

Building the documentation

The API reference is generated from the project's docstrings — nothing here needs to be hand-written or kept in sync manually. It uses:

• Sphinx — the doc build system
• sphinx-autoapi — walks dithertools/ and generates API pages directly from source (via AST, so it doesn't need to import the package or its dependencies)
• napoleon — parses the Google-style Args: / Returns: / Attributes: sections used in this codebase's docstrings
• furo — HTML theme

One-time setup

pip install -e ".[docs]"

Regenerate the docs

Whenever code, docstrings, or module structure change, rebuild with:

cd docs
make html

Output is written to docs/_build/html/. Open docs/_build/html/index.html in a browser to view it.

If make isn't available, the equivalent direct command from the project root is:

sphinx-build -b html docs docs/_build/html

Clean rebuild

Renamed or deleted modules can occasionally leave stale pages behind. If the output looks out of date after restructuring code, force a clean rebuild:

cd docs
make clean html

Notes

• docs/_build/ is gitignored — it's regenerated output, not source. Nobody needs to commit it; anyone with the repo can build it locally with the steps above.
• New modules under dithertools/ are picked up automatically on the next build — there's no per-module registration step. Just write the module with proper docstrings and rebuild.