Documentation workflow

← Back to Developer Guide

• API pages are generated with autodoc from module docstrings.

• Notebook pages are rendered natively by nbsphinx from the already-saved cell outputs in each .ipynb (nbsphinx_execute = 'never' — notebooks are never re-executed during the docs build, since several need GPUs / model downloads / hours of training). This gives notebook pages full Furo theming (fonts, colours, dark mode, sidebar), unlike the raw JupyterLab styling of a plain nbconvert export.

• Sphinx needs sources inside docs/, so a builder-inited hook in docs/conf.py (sync_notebooks) copies the top-level notebooks/ directory into docs/notebooks/ before every build. This is a real copy, not a symlink — a symlink breaks nbsphinx’s relative-path computation for extracted output images and silently drops every embedded figure from the build. docs/notebooks/ is gitignored and regenerated on each build; notebooks/ at the repo root remains the single source of truth.

• Each docs/notebook_examples/*.rst landing page links to its notebooks via :doc: references (e.g. :doc:`</notebooks/io/io_afm1>`) and a hidden toctree — update both when adding or removing a notebook.

• Build docs locally with make html inside docs/.