arborist/docs/_source/README.md

# Arborist API Reference (Sphinx)

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

## Build

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

Or directly:

```bash
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](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html).