.. _builddocs:

Building Documentation
======================

The narrative documentation and the Python API pages are written in
`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
and generated by `Sphinx <https://www.sphinx-doc.org/>`_. The tutorial pages are
the example notebooks (via ``nbsphinx``) and the C++ example programs (via
``literalinclude``). The C++ API reference is generated from Doxygen comments
with the Breathe and Exhale Sphinx plugins. The generated HTML is
GitHub Pages-ready.

Build with pixi
---------------

Pixi installs the documentation toolchain, generates the Python and C++ API
pages, runs Sphinx, and copies the final site into ``build/docs``:

.. code-block:: bash

   pixi run build-docs

The Python API generator imports ``pylupnt``. If ``python/pylupnt/_pylupnt*.so``
is missing, build the bindings first (``build-docs`` already depends on
``build-py``, so this is only needed for a manual build):

.. code-block:: bash

   pixi run build-py

The command writes ``build/docs/.nojekyll`` so GitHub Pages serves generated
directories such as ``_static`` without Jekyll filtering.

Previewing locally
------------------

Serve the generated site and open it in a browser:

.. code-block:: bash

   python -m http.server 8000 --directory build/docs

then visit http://localhost:8000. A local server (rather than opening the HTML
files directly) is recommended so in-page search and the interactive
visualizations load correctly.

Tutorial outputs
----------------

``nbsphinx`` is configured with ``nbsphinx_execute = "never"``, so the rendered
notebooks display the outputs **stored in** each ``.ipynb`` — the docs build
does not re-run them. After changing an example or an API it depends on, refresh
those stored outputs in place:

.. code-block:: bash

   pixi run render-notebooks                 # all notebooks
   pixi run render-notebooks -- --only ex16  # a subset

Interactive outputs render from a CDN at view time, so a network connection is
needed to see them: Plotly figures (ex12, ex14–ex16) pull ``plotly.js``, and the
Cesium scenes (ex13) — self-contained HTML written to
``docs/_static/cesium_scenes/`` and linked from the page — pull ``CesiumJS``.
Static Matplotlib figures are embedded as images and always render.

Manual build
------------

If you are not using pixi, first build the C++ library and Python bindings, then
install the Python and system documentation dependencies and run the build
script:

.. code-block:: bash

   cd docs
   pip install -r requirements.txt
   brew install doxygen pandoc          # macOS
   sudo apt-get install doxygen pandoc  # Linux
   python make_docs.py

The generated HTML is written to the repository-level ``build/docs`` folder.