Documentation Requirements

Since the beginning of Tethys Platform, we have always placed high priority on documentation of features. As such, one of the things that will be checked when reviewing contributions is sufficient documentation of the features being added. If it isn't documented, it doesn't exist to end users.

Documentation exists in the docs directory and in the documentation strings of classes and methods. The html pages for the Tethys Platform documentation website are built from ReStructured Text (rst) files using Sphinx. Refer to the Sphinx documentation for an explanation of the ReStructured Text format. There are also many examples to refer to in the documentation.

To develop the documentation, you'll need to build the tethys-docs conda environment. From the Tethys source directory:

$ cd docs
$ conda env create -f docs_environment.yml

To build the documentation, activate the tethys-docs environment and use the make file provided by Sphinx. From the docs directory:

$ conda activate tethys-docs
$ (tethys-docs) make html

This will generate a _build directory with the html files. You can open any of these html files in a web browser to preview how the docs will look. Do not commit anything in the _build directory. Every time you make a change to the ReStructured Text files, you will need to run make html to update the html files.

Sphinx uses a caching mechanism to build only the files that changed to speed up development. Sometimes, it is necessary to do a complete rebuild of the documentation to accurately reflect changes (usually after adding new ReStructure Text files or otherwise modifying the navigation). To do so, simply delete the _build directory and run make html.