Writing documentation

The documentation follows the Diátaxis framework. Every page is one of four kinds, and each kind has its own folder under docs/source:

Kind	Folder	Answers	Written for
Tutorial	`tutorials/`	“Teach me”	Someone learning the GUI, on the sample data
How-to guide	`how-to/`	“How do I …?”	Someone who knows the GUI and has a task to do
Explanation	`explanation/`	“Why …?”	Someone who wants to understand
Reference	`reference/`	“What exactly is …?”	Someone looking up a fact

A page does one of these jobs. When a tutorial needs to explain something, or a how-to needs a full table of options, link to the explanation or reference page instead of including it.

Page templates

Tutorial

What you’ll do: one sentence, and a picture of the result.
Before you start: what to install and which data to download.
Numbered steps. Each step that changes the display ends with what the learner should see.
What you’ve learned.
Next steps: links to the next tutorial and related pages.

Tutorials never offer alternatives (“if you use OpenEphys …”). They use the sample data, so every step has one right outcome.

How-to guide

Title starting “How to …”.
One sentence on the goal.
Prerequisites.
Steps.
Related: links to the reference and explanation pages.

How-to guides can be short. They assume the reader already knows the GUI.

Explanation

The question the page answers.
Discussion, with diagrams where they help.
Trade-offs and limits.
Further reading.

Explanation pages contain no steps to follow and no exhaustive option lists.

Reference

One sentence on what the page covers.
Entries in a consistent format: the same fields for every item.
Defaults and fallbacks stated for every option.

Reference pages contain no instructions. Tables of keyboard shortcuts, session YAML keys and datasets live only in reference/; other pages link to them rather than repeating them.

Files and labels

New pages are Markdown (.md), parsed by MyST. Only api.rst, changelog.rst and the autosummary templates are reStructuredText.
File names are lowercase with underscores, e.g. how_alignment_works.md. Tutorials are numbered, e.g. 01_first_alignment.md.
Every page starts with a label, prefixed by its kind, so that it can be linked to wherever it lives:
```
(ref-session-yaml)=
# Session YAML
```
Prefixes: tutorial-, howto-, explanation-, ref-, contributing-.
Link to pages through their label, {ref}`ref-session-yaml`, rather than their path, so that moving a page doesn’t break links to it.
When a page moves or is removed, add its old path to redirects in conf.py.

MyST syntax used in these docs

Keyboard shortcut:        {kbd}`Shift+A`
Link to a label:          {ref}`ref-session-yaml`
Link with custom text:    {ref}`the session YAML keys <ref-session-yaml>`
Link to a page:           {doc}`../installation`
Python object:            {class}`~ibl_alignment_gui.loaders.data_loader.DataLoaderLocal`
Package version:          {{ version_code }}

```{note}
An admonition. Also: warning, tip, important.
```

```{list-table}
:header-rows: 1
:widths: 30 70

* - Shortcut
  - Action
* - {kbd}`Enter`
  - Apply the fit
```

::::{tab-set}
:::{tab-item} Linux and macOS
...
:::
:::{tab-item} Windows
...
:::
::::

:::{dropdown} Title
Hidden until clicked.
:::

Simple tables can use the Markdown pipe syntax instead of list-table.

Placeholders

Mark anything still to be written with a TODO admonition, so it stands out on the page:

:::{admonition} TODO
:class: warning

Screenshot of the GUI after loading the data.
:::

Pages with placeholders can be merged into working branches, but the documentation workflow fails on any TODO in a pull request to main, so they cannot reach the published site.

Images

Screenshots go in _static/, in a folder per page, e.g. _static/tutorials/01_first_alignment/. Take GUI screenshots at the same window size (1600 × 1000) and in the light theme, so that pages look consistent.

Building

uv run --group doc sphinx-build -W --keep-going docs/source docs/build

-W turns warnings into errors, as in CI, so a broken link or cross-reference fails the build. Open docs/build/index.html to view the result. To rebuild automatically while editing:

uv run --group doc sphinx-autobuild docs/source docs/build