Editing & Building the Docs
===========================

The GLASS documentation is built with **Sphinx** (``pydata-sphinx-theme``),
with the API reference generated by **Doxygen** and bridged into Sphinx via
**Breathe**. Everything lives under ``docs/``.

Layout
------

.. code-block:: text

   docs/
   ├── Doxyfile            # Doxygen config (XML output for Breathe)
   ├── Makefile            # `make all` = clean + doxygen + html
   ├── requirements.txt    # Sphinx + breathe pins
   └── source/
       ├── conf.py         # Sphinx config (breathe_projects -> ../doxygen/xml)
       ├── index.rst       # landing page + the top-level navbar toctrees
       ├── _static/        # committed images (e.g. the sweep-ladder figures)
       ├── api_reference/  # Breathe `.. doxygenfile::` pages (auto-generated API)
       ├── user_guide/     # hand-written narrative (getting_started/concepts/tutorials)
       └── {contribution_guidelines,sphinx_edit_guide}.rst  # Developer Guide section

Site navigation
---------------

The top navbar is built from the ``:caption:`` toctrees in ``index.rst`` —
**Getting Started · Concepts · Tutorials · API Reference · Developer Guide**.
Each narrative section owns an ``index.rst`` (e.g.
``user_guide/getting_started/index.rst``) whose ``.. toctree::`` lists its child
pages; that toctree is what populates the left sidebar when you are inside the
section. **To add a page, add it to its section's** ``index.rst`` **toctree** —
do not list leaf pages directly in the root ``index.rst`` (that flattens the
hierarchy and leaves the sidebar empty on deep pages). Keep one index page per
navbar section so the sidebar always shows sibling pages.

Build locally
-------------

.. code-block:: bash

   python -m venv docs/.venv
   docs/.venv/bin/pip install -r docs/requirements.txt
   # Doxygen is a system package:
   sudo apt-get install -y doxygen

   cd docs
   make all          # runs doxygen, then sphinx-build
   # open build/html/index.html

``make all`` regenerates the Doxygen XML (``docs/doxygen/xml/``) and then the
HTML site (``docs/build/html/``). Both directories are gitignored.

How the API reference works
---------------------------

* Doxygen parses the headers (see ``INPUT`` in ``Doxyfile``) and emits XML for
  every symbol that carries a ``/** */`` doc-comment (``EXTRACT_ALL = NO``).
* The ``api_reference/*.rst`` pages pull those in per-file with
  ``.. doxygenfile:: src/base/L1/axpy.cuh`` (paths are stripped of the leading
  ``../`` via ``STRIP_FROM_PATH``).
* To document a new header, add a ``/** */`` block in the source **and** a
  ``.. doxygenfile::`` line on the matching page. Undocumented internals simply
  don't appear — no broken references.

Editing narrative pages
------------------------

The ``user_guide/`` pages are plain reStructuredText. Use ``=== / --- / ~~~``
for the heading levels, ``.. code-block:: cpp`` / ``bash`` for snippets, and
``:doc:`` roles for cross-references. The site is published to GitHub Pages on
every push to ``main`` via ``.github/workflows/gh-pages.yml``.