Zilinghan/readthedoc

[Zilinghan]

Summary

Turns docs/ into a proper Sphinx site written in MyST-Markdown and adds the .readthedocs.yaml needed to publish it on Read the Docs.

The five existing reference docs (configurations, model_harness, drift_detectors, continuous_learning, tracking) are unchanged in substance — they become pages in the site. Around them this adds the pages we did not have: an installation guide, a quickstart, an architecture overview, a detector decision guide, a FLOPS-profiler page, a deployment page, an agent-skills page, and an autodoc API reference generated from the docstrings in src/apeiron/.

Nothing about how the framework runs changes. The only non-docs edit is two docstring fixes in configuration.py (details below).

What's here

Area	Files
Sphinx config	docs/conf.py, docs/requirements.txt, docs/_static/custom.css
Read the Docs config	.readthedocs.yaml
New pages	docs/{index,installation,quickstart,architecture,choosing_a_detector,profiler,deployment,agent_skills}.md
API reference	docs/api/*.md (9 files, autodoc over src/apeiron/)
Existing pages	wired into the navigation; content unchanged except the fixes below

Theme is Furo, with sphinx-design (grids, tabs), sphinx-copybutton, and sphinxcontrib-mermaid for the flow diagrams in architecture.md and agent_skills.md.

Build it locally

Docs dependencies are deliberately separate from the project's. docs/conf.py mocks torch, river, evidently, wandb, and mlflow via autodoc_mock_imports, so a docs build does not need the poetry environment or a GPU-specific torch wheel — it's ~40 MB of Sphinx and nothing else.

# one-time
python3 -m venv .venv-docs
.venv-docs/bin/python -m pip install -r docs/requirements.txt

# build
.venv-docs/bin/python -m sphinx -b html -W --keep-going docs docs/_build/html
open docs/_build/html/index.html

Important

Invoke it as .venv-docs/bin/python -m sphinx, not as bare sphinx-build. If you have conda on your PATH, its shell hook re-prepends itself ahead of an activated venv, so sphinx-build can resolve to a different interpreter that has no myst_parser installed — you get Could not import extension myst_parser even though your venv is fine. Calling the venv's interpreter by absolute path avoids PATH entirely.

-W turns warnings into errors and --keep-going reports all of them rather than stopping at the first. Keep both: Read the Docs is configured with fail_on_warning: true, so a build that is clean locally is a build that will succeed there. The site currently builds clean under -W.

Iterating on a page:

.venv-docs/bin/python -m pip install sphinx-autobuild
.venv-docs/bin/python -m sphinx_autobuild docs docs/_build/html   # live reload on :8000

If you edit conf.py, force a full rebuild — Sphinx caches aggressively:

rm -rf docs/_build && .venv-docs/bin/python -m sphinx -b html -W docs docs/_build/html

Mermaid diagrams render client-side, so the local page needs network access to fetch mermaid.js.

Publishing to Read the Docs (after merge)

This PR only lands the config — someone with repo admin rights has to do the one-time import. .readthedocs.yaml must be on main first, since RTD builds its latest version from the default branch, so merge this before importing.

1. Pick the right site. Community cannot build a private repo:

Repo visibility	Site	Cost
Public	readthedocs.org	Free
Private	app.readthedocs.com	Paid, trial available

Check with gh repo view AI-ModCon/BaseSIM_APEIRON --json visibility.

2. Import the project.

• Sign in with GitHub and authorize the AI-ModCon organization. An org owner may need to approve the OAuth app — this is the usual place the import stalls.
• Add project → Configure automatically, select AI-ModCon/BaseSIM_APEIRON.
• Set the project name to apeiron. The name becomes the slug becomes the URL: https://apeiron.readthedocs.io. Worth getting right on the first try, since changing it later breaks every published link.
• Confirm. RTD detects .readthedocs.yaml and starts the first build.

3. Watch the first build under the Builds tab. It runs the same Sphinx command as above on Ubuntu 24.04 / Python 3.13, installing only docs/requirements.txt. Because fail_on_warning: true is set, a single warning fails it. The site is warning-clean today, but RTD's Python 3.13 could surface something a local 3.11 venv does not — if so, fix the warning or temporarily flip that key in .readthedocs.yaml.

4. Afterwards. The import installs a GitHub webhook, so every push to main rebuilds and redeploys with no further action. Worth enabling once:

• Admin → Settings → Build pull requests for this project — preview builds on every PR, which pairs well with fail_on_warning.
• Admin → Versions — activate git tags for versioned docs (/en/v0.1.0/ next to /en/latest/).
• Badge for the top-level README.md:

  [![Docs](https://readthedocs.org/projects/apeiron/badge/?version=latest)](https://apeiron.readthedocs.io/en/latest/)

Notes for reviewers

Two docstring fixes in src/apeiron/config/configuration.py — the only change outside docs/. Both were breaking the docs build, neither changes behavior:

• get_available_device — the nested bullet list had no blank lines, so docutils parsed it as a malformed definition list.
• env_overrides — Defaults to "APP_" was parsed as an RST link target because of the trailing underscore, producing ERROR: Unknown target name: "app". Now APP_ .

Docs updated for the EnsembleDetector work in #114. choosing_a_detector.md gained a "Combine detectors with an ensemble" section covering the voting rules, the one-instance-per-detector-type constraint, and the fact that warm-up is governed by the slowest sub-detector. Also added the ensemble to the pick-a-detector table and a paste-ready TOML tab.

Path consistency. continuous_learning.md (8 spots) and model_harness.md (1) still had pre-restructure src/training/... paths; now src/apeiron/training/..., matching the fix already applied to the other pages in #113.

.gitignore. Two negations were needed: the repo-wide *.txt was swallowing docs/requirements.txt, which would have broken the RTD build. Also added .venv-docs/.

Where to look first. docs/index.md defines the whole navigation via its toctrees — any new page must be listed there or Sphinx warns that it is orphaned. docs/README.md has the page map and the local conventions.

Known gap. deployment.md and profiler.md use MyST {include} to pull in READMEs that live next to the code (src/apeiron/deployment/*/README.md, src/apeiron/profilers/README.md) so those pages track the scripts they document. If you move or rename those READMEs, the docs build fails.

[anagainaru]

Looks good