Sphinx Documentation

Generating the documentation

To generate the documentation files, you will need to install Sphinx using:

pip -m install sphinx
pip -m install sphinx-design sphinx-argparse sphinxcontrib-plantuml sphinxcontrib.programoutput sphinx_rtd_theme
pip -m install scipy

Then you can generate the documentation files with the following commands:
```
cd /path/to/GEOS/build-your-platform-release
make geosx_docs
```

That will create a new folder

/path/to/GEOS/build-your-platform-release/html/docs/sphinx

which contains all the html files generated.

Documenting the code

The documentation is generated from restructured text files (.rst). Most files can be found in src/docs/sphinx. Files which are specific to parts of the code, like those describing a specific class, can instead be found in docs subdirectory in the folder containing the source code.

Information about how to write rst files can be found here .

Fixing errors the documentation

As part of the Continuous Integration process, the documentation is built on readthedocs, and any warnings or errors result in a failure test failure. What follows is a brief guide on how to fix the most common errors.

Navigate to the readthedocs build logs. This can be done by clicking on the failed test in the github test summary.

../../../../_images/githubtestsummary.png

Download the logs from the failed test on readthedocs through the “view raw” button.

../../../../_images/readthedocsbuildsummary.png

#. Perform a case sensitive search for “WARNING:” or “ERROR” to locate the sphinx issues. Note that there will be numerous doxygen warnings that should be ignored.