sphinx_edit_guide.rst

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

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

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.