arborist/docs/_source/README.md

Arborist API Reference (Sphinx)

This directory contains Sphinx configuration to generate API documentation from docstrings.

Build

cd docs/_source
make html           # Generate HTML (output: _build/html/)
make text           # Generate text (output: _build/text/)
make clean          # Remove build artifacts

Or directly:

sphinx-build -b html . _build/html

View

After building, open _build/html/index.html in a browser.

Structure

• conf.py — Sphinx configuration
• index.rst — Main table of contents
• api/ — Module documentation (one .rst per module category)
  • substrate.rst — Core data structures (merkle, document, wikitext)
  • storage.rst — SQLite schema (store, ingest, evict)
  • retrieval.rst — FTS5 search (search, sources, concepts)
  • qa.rst — Q&A pipeline (runner, query, verify, evidence, etc.)
  • distill.rst — Distillation (surface→core)
  • mesh.rst — Federation (gossip-based sync)
  • cli.rst — Command-line interface

What it replaces

This generated documentation replaces docs/modules.md (1200+ lines of static API reference). The docstrings in code are the source of truth; Sphinx extracts them automatically.

Adding new modules

1. Add a docstring to the module (module-level docstring at the top of module.py)
2. Add an .rst file in api/ that includes the module with automodule directive
3. Reference it in index.rst
4. Rebuild with make html

Theme

Uses furo theme (modern, responsive, search-enabled).

Autodoc directives

The .rst files use Sphinx automodule to extract:

• Module docstrings
• Class docstrings + members
• Function signatures + docstrings
• Source code links (:viewcode: extension)

See Sphinx autodoc docs.