# ADR-09: Docs stack

**Status**: accepted (2026-05-28)
**Blocks**: workstream C (maturity).

## Context

dag-ml and dag-ml-data both ship raw markdown today (`docs/*.md`). The integration plan demands a hosted, contributor-friendly site that links to API reference. Choice: Sphinx (Python-ecosystem-friendly), mdBook (Rust-ecosystem-friendly), Docusaurus (JS-ecosystem-friendly).

## Decision

**Sphinx + MyST for prose; rustdoc/docs.rs for the API reference; one landing page per repo linking both.**

Rationale:
- Sphinx + MyST renders the existing `.md` files unchanged (no rewrite required).
- nirs4all already ships Sphinx; reusing the same toolchain reduces the maintenance footprint and lets bridge contributors learn once.
- rustdoc auto-publishes on crates.io release (workstream D); pointing the landing page at `https://docs.rs/dag-ml-core/latest/` gives a free always-current API reference.
- mdBook would split the contributor experience (Rust API vs prose vs Python wheels in three places). Sphinx unifies it.

### Concrete layout

```
docs/
├── conf.py                  # Sphinx config (MyST + sphinx_design + sphinx_copybutton)
├── index.md                 # landing page; links to ADRs / STATUS / API ref
├── installation.md
├── architecture.md          # symlink or include of ARCHITECTURE.md
├── adr/                     # numbered ADRs (this directory)
├── contracts/               # JSON schemas (existing)
├── design/source/           # historical specs (existing)
└── _build/                  # gitignored
```

### Hosting

- GitHub Pages on tag-push from `main` (workstream C task 5 + ADR-10 release train).
- rustdoc auto-published via crates.io on `cargo publish` (ADR-10).

## Consequences

- Workstream C task 5 adds Sphinx config + GitHub Pages workflow per repo.
- nirs4all's existing Sphinx pipeline serves as the template (the sibling `nirs4all` repo's `docs/source/conf.py`).
- The site replaces `docs/TOC.md` as the canonical navigation entry point (TOC.md remains in-repo as the source).

## Risk

- Sphinx requires Python build dependencies even though the projects are Rust. CI installs them in the docs job only — the build/test gate stays Rust-only. Acceptable.