Documentation

AMR-Wind comes with two different types of documentation:

The manual, i.e., the document you are reading now, that is written using Sphinx, and
Inline documentation within C++ source code that are written in a format that can be processed automatically by Doxygen

Manual

The AMR-Wind manual is written using a special format called ReStructured Text (ReST) and is converted into HTML and PDF formats using a python package Sphinx. Since the manuals are written in simple text files, they can be version controlled alongside the source code. Documentation is automatically generated with new updates to the GitHub repository and deployed at AMR-Wind documentation site.

Writing documentation

As mentioned previously, documentation is written using a special text format called reStructuredText. Sphinx user manual provides a reST Primer that provides an overview of this format and how to write documentation using this format.

Source code documentation

Source code (C++ files) are commented using a special format that allows Doxygen to extract the annotated comments and create source code documentation as well as inheritance diagrams. The AMR-Wind API documentation for the latest snapshot of the codebase can be browsed in this manual. The Doxygen manual provides an overview of the syntax that must be used. Please follow the Doxygen style of commenting code when commenting AMR-Wind sources.

When commenting code, try to use self-documenting code, i.e., descriptive names for variables and functions that eliminate the need to describe what is going on in comments. In general, comments should address why something is being coded in a particular way, rather than how the code does things. Try to write the code in a clear manner so that it is obvious from reading the code instead of having to rely on comments to follow the code structure.

Building documentation

Dependencies

To generate the AMR-Wind manual on a local machine, doxygen, graphviz, doxysphinx, enchant, and sphinx are required.

To install the required packages on Linux:

$ sudo apt-get install -y --no-install-recommends graphviz libenchant-2-dev

and on OSX with homebrew:

$ brew install doxygen graphviz enchant

To install the required python packages:

$ pip install sphinx sphinx_rtd_theme sphinx_toolbox sphinx_copybutton pyenchant sphinxcontrib-spelling doxysphinx

Build

Run the following command to build the documentation:

$ cd build && cmake -DAMR_WIND_ENABLE_DOCUMENTATION:BOOL=ON .. && cmake --build . -t docs

Tip

On OSX, before running the cmake, you may need to $ export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.dylib

The resulting documentation is in docs/spinx/html directory. Documentation can also be generated in other formats, consult Sphinx docs for available formats and their usage.