Writing documentation for OFT

The Open FUSION Toolkit uses Doxygen to create structured and navigable documentation from the source code and structured comments. When adding new components or modifying existing elements the associated documentation should be updated to allow easy reference. For information on Doxygen specific commands which can be used to supplement documentation see the Doxygen documentation.

Building the documentation

The recommended way to build the documentation locally is to create a "docs only" build by creating a suitable directory and running cmake with the options -DOFT_BUILD_DOCS:BOOL=ON and -DOFT_DOCS_ONLY:BOOL=ON and then running make docs. Once OFT is built, the documentation will be available at doc/Documentation.html in the build directory. For example

mkdir build_docs
cd build_docs
cmake -DOFT_BUILD_DOCS:BOOL=ON -DOFT_DOCS_ONLY:BOOL=ON /path/to/oft/src
make docs

Note: There is no need to run make install. If you would like to "install" the documentation you should add a suitable path with -DDCMAKE_INSTALL_PREFIX.

Building the documentation requires that Doxygen is installed and available in the users PATH. Additionally, to create diagrams and certain other visuals in the documentation the dot command must also be available, which is provided in the Graphviz package. Both Doxygen and Graphviz can be installed using standard package managers (apt, brew, etc.).

Doxygen+Graphviz installation with homebrew

brew install doxygen graphviz

Doxygen+Graphviz installation with apt

apt install doxygen graphviz

In-source documentation format

In-source documentation blocks allow automatic generation of documentation from the source code, while also providing information within the source itself for developers. This is done through the use of formatted comment blocks, as described below. Within a comment block a sub-set of markdown syntax can be used (see link for more information). Additionally, latex-based equations can also be added using the \f$ or @f$ tags for inline equations (see link for more information).

Documenting Fortran code

In Fortran, Doxygen comment blocks are started with either a !< or !> to document the last and next item respectively. After starting a comment block you can continue it using !! on the next line. For programs, modules, and subroutines/functions the documentation should be placed just before the definition of the scope and enclosed in a sentinel block as shown in the example below. For variables, documentation should be started on the same line as the definition. A short example of how to document a subroutine using this approach is given below. For more examples, please view the OFT source code.

!---------------------------------------------------------------------------
!> Project a scalar field onto a finite element basis and compute its integral
!!
!! For a given basis set \f$ \phi \f$, the j-th value of the projected field is
!! \f$ \int \phi_j f dV \f$.
!---------------------------------------------------------------------------
SUBROUTINE project_and_integrate(in_field,projected_field,field_integral)
CLASS(fem_interp), intent(inout) :: in_field !< Input field for projection
CLASS(oft_vector), intent(inout) :: projected_field !< Output field after FE projection \f$ \int \phi^T \f$
REAL(r8), intent(out) :: field_integral !< Volume integral of in_field

Documenting Python code

In Python, OFT uses Doxygen comment blocks as part of docstrings for classes and functions, which are started with r'''! to tell Doxygen to parse the docstring block. Note that the r''' is required to avoid syntax warnings related to \f$ and other Doxygen commands.

Function arguments must be documented using an @param command for each argument, as shown in the example below. For variables, documentation should be given before the variable is defined using a ## to start the comment. Please note, that for classes where variables may be set in multiple places you should only do this once and in a place that is clear and easy to keep track of. A short example of how to document a class and subroutine using this approach is given below. For more examples, please view the OFT source code.

def example_class():
    def __init__(self,mesh):
        ## Finite element mesh
        self.mesh = mesh

def project_and_integrate(in_field,projected_field,field_integral):
    r'''! Project a scalar field onto a finite element basis and compute its integral

        For a given basis set \f$ \phi \f$, the j-th value of the projected field is
        \f$ \int \phi_j f dV \f$.

        @param in_field Input field for projection
        @param projected_field Output field after FE projection \f$ \int \phi^T \f$
        @param field_integral Volume integral of in_field
    '''

Documentation Pages

In addition to in-source documentation, there are individual pages that contain additional documentation related to functionality and use of OFT. These pages should be created in the src/docs folder using Markdown format with the *.md extension. Pages can be referenced by other pages using the \ref or @ref commands and nested under other pages using the \subpage or @subpage commands. Note that both commands will create a link, but \subpage will also introduce a hierarchy by make the referenced page a child of the referencing page. An example of a simple page is shown below and additional examples can be found in the src/docs folder.

Magnetohydrodynamics on Unstructured Grids (MUG): 3D linear/nonlinear extended MHD simulation package     {#doc_mug_main}
================

[TOC]

Initial description of MUG.

\section doc_mug_main_ex MUG Examples
The following examples illustrate usage of MUG to run time-dependent Hall-MHD simulations. 

 - \subpage doc_mug_ex1
 - \subpage doc_mug_ex2

Jupyter Example notebooks

To create a Jupyter example, place it in the appropriate folder and add a Markdown block at the top of the file with the following syntax.

Example XX: This is the title of the example     {#doc_my_example}
================

In Markdown blocks lines beginning with **Note:** and **Warning:** will also be converted to \note and \warn blocks to be highlighted specifically in the Doxygen-generated documentation.

**Note:** This is a note.

**Warning:*** This is a warning!

Doxygen Commands

TODO: Provide a listing of useful Doxygen commands.