.. _developer-guide-documentation:

**************************
Building the Documentation
**************************

The documentation is built with `Sphinx <https://www.sphinx-doc.org>`_ using
the `pydata-sphinx-theme <https://pydata-sphinx-theme.readthedocs.io>`_,
styled after the `MolSSI SEAMM documentation <https://molssi-seamm.github.io>`_.

Building locally
================
.. code-block:: bash

   pip install -e ".[docs,gnn,ase]"
   cd docs
   make html

The site lands in ``docs/_build/html``; open ``index.html`` in a browser.
``make clean`` removes the build and the generated API stubs
(``docs/api/generated``).

The API reference is generated by ``sphinx.ext.autosummary`` from the
docstrings in ``src/xnn``, so the package (and its ``gnn``/``ase`` extras)
must be importable when the docs build.

Deployment
==========
The site is published to GitHub Pages by the workflow in
``.github/workflows/docs.yml``: every push to ``main`` builds the docs on a
CPU-only torch install and deploys ``docs/_build/html`` via
``actions/deploy-pages``. Pull requests build the docs (without deploying)
so breakage is caught early.

Layout
======
.. code-block:: text

   docs/
     conf.py             Sphinx configuration (theme, autodoc, autosummary)
     index.rst           landing page
     getting_started/    installation, quickstart, first training
     how_tos/            task-oriented recipes
     background/         design and model-fidelity notes
     user_guide/         reference documentation
     developer_guide/    this section
     api/                autosummary entry point (stubs generated at build)
     _static/            MolSSI palette CSS, logos
     _templates/         MolSSI footer, autosummary templates