Sphinx
======

`Sphinx <https://www.sphinx-doc.org/en/master/>`_ is the documentation generator that reads the ``.rst`` files under
``source/`` and renders the static site in ``_build/html``. It is configured entirely through ``source/conf.py``.

Extensions enabled in ``conf.py`` for this project:

.. code-block:: python

    extensions = [
        'sphinx.ext.extlinks',
        'sphinx.ext.intersphinx',
        'sphinx.ext.todo',
        'ablog',
        'sphinxcontrib.youtube',
        'sphinx.ext.mathjax',
        'sphinx-mathjax-offline',
        'numpydoc',
        'sphinx.ext.graphviz',
        'sphinx_design',
    ]

The site uses the `pydata_sphinx_theme <https://pydata-sphinx-theme.readthedocs.io/>`_ HTML theme (set via
``html_theme`` in ``conf.py``). `sphinx_design <https://sphinx-design.readthedocs.io/>`_ provides the cards and
grids on the home page, and ``sphinx.ext.graphviz`` needs Graphviz's ``dot`` on the ``PATH``.

To build the HTML pages locally:

.. code-block:: bash

    $ sphinx-build -M html source _build          # writes to _build/html
    $ python -m http.server -d _build/html        # preview at localhost:8000

See :doc:`build` for the full local development and deployment loop, and ``requirements.txt`` in the
project root for the Sphinx and extension packages to install.