=====================================
Building documentation for nmrglue-ng
=====================================

nmrglue-ng uses Sphinx, Sphinx Book Theme, and MyST-NB for building its
documentation. Install them through the ``docs`` optional dependency extra
from ``pyproject.toml``.

Instructions
------------

1.  Create and activate a Python environment. For example:

        python -m venv .venv
        . .venv/bin/activate

    Or use the project's mamba environment:

        mamba activate nmrglue-ng-dev

2.  Install nmrglue-ng and the documentation dependencies in editable mode from
    the repository root directory.

        python -m pip install -e '.[docs]'

3.  Run ``make html-fast`` in this directory for the default build (no API
    reference).

The HTML pages are written to ``build/html/``.

Build targets
-------------

The default build is fast and omits the generated API reference. The API
reference is built only on explicit request (``make html``).

========================  ============================================================
Target                    Output
========================  ============================================================
``make html-fast``        English, no API reference → ``build/html/``
``make html``             English with API reference → ``build/html/``
========================  ============================================================

The API reference is expensive to build and is not needed for tutorial,
navigation, or theme work. Use ``make html`` only when API pages and links
must be verified.

English-only documentation
--------------------------

English is the only documentation language. There is no gettext catalog and no
language selector; the site is built once, in English, at the version root.
Translate tutorial prose and headings when rewriting pages, but never translate
Python identifiers or code-cell input.

MyST-NB execution cache
----------------------

Routine HTML builds use MyST-NB's ``cache`` execution mode with a cache under
``doc/build/.jupyter_cache``. This avoids re-executing unchanged notebooks while
still executing new or changed notebooks. Before release, run a clean build from
an empty ``doc/build`` directory or override the mode with
``-D nb_execution_mode=force`` to prove the notebooks execute from scratch.

Downloadable tutorials
----------------------

Each MyST tutorial uses the ``nb-download`` role to link to the executed
``.ipynb`` generated by MyST-NB. The accompanying ``download`` role copies its
small versioned synthetic fixture into the HTML downloads. Markdown remains
the notebook source of truth; there is no separately maintained notebook copy.
To check portability, save both linked files into a folder outside the checkout
and run all cells with a fresh kernel using an installed nmrglue-ng wheel.

ReadTheDocs
-----------

Read the Docs builds are configured by ``../.readthedocs.yml``. The configured
Python version must remain compatible with ``requires-python`` in
``pyproject.toml``.
