Documentation Practices
=======================

Introduction to Editing the Sphinx Documentation
------------------------------------------------
Documentation for WESTPA is maintained using `Sphinx <https://sphinx-doc.org/>`_.
Docstrings are formatted in the `Numpy style
<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_,
which are converted to ReStructuredText using Sphinx' `Napoleon
<http://sphinxcontrib-napoleon.readthedocs.org/en/latest/>`_ plugin, a feature included with Sphinx.

Make sure ``sphinx`` and ``sphinx_rtd_theme`` are installed on the system. The settings for the documentation 
are specified in ``/westpa/doc/conf.py``. In order to successfully build the documentation, your system 
has to statisfy the minimum environment to install WESTPA.

The documentation may be built locally in the ``_build`` folder by navigating to the ``doc`` folder, and
running::

  make html

to prepare an html version or::

  make latexpdf

To prepare a pdf. The latter requires ``latex`` to be available.

Uploading to ReadTheDocs
------------------------
The online copy of WESTPA Sphinx documentation is hosted on `ReadtheDocs <https://readthedocs.org>`_. 
The Sphinx documentations on the main branch are updated whenever the main branch is updated, via a 
webhook setup on ReadtheDocs and ``/westpa/.readthedocs.yml``. The environment used to build the documentation
on the RTD servers are described in ``/westpa/doc/doc_env.yaml``.

In Cases of Major Revisions in Code Base
----------------------------------------
Currently, each ``.rst`` file contains pre-written descriptions and autogenerated sections generated 
from docstrings via ``automodule``.  In cases where the WESTPA code base has significantly changed, 
the structure of the code base can be regenerated into the ``test`` folder by running the 
following command in the ``doc`` folder::

  sphinx-apidoc -f -o test ../src/westpa