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.

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

../../../../_images/githubtestsummary.png
  1. 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.