How to develop documentation

Documenting Proteus

Documenting Proteus is mostly the same as documenting the Python language. In particular, each module, class, function, and data member may have an associated docstring. A docstring can be plain text, or it can also use reStructuredText markup. Here is an example:

def midpoint(x,y):
  """
  Find the midpoint of x and y

  Computes the midpoint of Euclidian vectors x and y.

  :param x: point as numpy.array
  :param y: point as numpy.array
  :return m: midpoint as numpy.array
  """"

There are two acceptable documentation standards used in Proteus, the Numpy standard or the Google standard. In general the Numpy standard is preferred but this is not a hard and fast rule. While the documentation in many parts of the library do not adhere to these standards, we are working to update older documentation and new additions to the library should use these standards (pull requests updating documentation are greatly appreciated too!)

For examples of proper documentation see here and here.

Building the documentation

Proteus uses the Sphinx tool to generate different formats of the documentation from the docstrings and from a few additional reStructuredText files. By default, the proteus stack doesn't contain all the dependencies required to build the documentation. You need to also install graphviz, which is available in most Linux distributions. To build the html documentation (i.e. the proteus website) run:

make doc

That make command will also try to open the documentation in your browser when finished, but the local version of the website will be:

../proteus-website/index.html

Sphinx extends reStructuredText with additional directives and provides an excellent reStrucuredText primer as well as descriptions of the extensions. Of particular note are the directives for math in LaTeX:

"""
Inline math :math: x^2 + y^2

Display math

.. math::
   x^2 + y^2 = 1
"""

Modifying or adding documentation

You can use the same branch and pull request workflow for documentation changes as for source changes since others can review by generating the documentation locally.

Important files

Not all the documentation is generated from docstrings. There are several important files

• doc/source/index.rst: The landing page for
• doc/source/conf.py: The Sphinx configuration file
• doc/source/_static: Images and other static content
• doc/source/_templates/layout.html: HTML template for page layout
• doc/Doxyfile: The Doxygen config file for extracting C/C++/Fortran source

Maintainers: Updating the proteustoolkit.org website

The website is hosted by github using the project pages mechanism, which simply means that the html source for the website is the gh-pages branch of the proteus repository. To set your machine up for updating the gh-pages branch do (from the proteus directory):

cd ..
rm -rf proteus-website
git clone https://github.com/erdc-cm/proteus -b gh-pages proteus-website

Then you can add and commit changes in the proteus-website directory as needed to update the gh-pages branch. Finally, push your changes to github to have the changes reflected on proteustoolkit.org. Note: to make suggested changes to the documentation don't branch from gh-pages, branch from master and ask other developers to review the changes by regenerating the documentation locally. Only add/commit/push to gh-pages when you are ready to publish the website. If you want to experiment with he gh-pages branch and a test website hosted by github, then fork proteus and use the gh-pages branch on your fork.