=====================================
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), or ``make html-all`` for all languages.

The HTML pages are written to ``build/html/<language>/``.

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/en/``
``make html-fr``          French, no API reference → ``build/html/fr/``
``make html-es``          Spanish, no API reference → ``build/html/es/``
``make html-all``         All languages + root redirect → ``build/html/``
``make html``             English with API reference → ``build/html/en/``
``make gettext``          Extract translation templates → ``build/gettext/``
========================  ============================================================

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.

Multilingual builds
-------------------

English is the canonical documentation language. Translation catalogs live in
``source/locale/<language>/LC_MESSAGES/``. Extract messages with ``make gettext``
and update catalogs with ``sphinx-intl update -p build/gettext -l fr -l es``.

Build all languages with:

    make html-all

This creates ``build/html/en/``, ``build/html/fr/``, ``build/html/es/``, and a
root ``build/html/index.html`` redirect. The top-bar language selector links
between the ``en/``, ``fr/``, and ``es/`` directories.

The API reference remains English-only for now; translate tutorial prose and
headings, 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``.
