Writing DocumentationΒΆ

Documentation is written using the reStructuredText language and is then converted into html via python/sphinx (see section Building the documentation for details on how the documentation is built). Here we briefly outline the procedures for writing documentation pages without discussing the syntax of the reStructuredText language. Syntax details can be found in the Quick reStructuredText user guide, the RestructuredText Primer, or the Sphinx RST Style guide.

Currently the documentation is organized into three chapters:

  1. User Manual
  2. Developer Manual
  3. Theory Manual

The content of the individual chapters is fairly self-explanatory. Casual users should be able to obtain all of the information required to install and run the code and its associated tools from the User Manual. Code developers will need to refer to the Developer Manual for software-related instructions and to the Theory Manual for technical details regarding the flow solver and supporting tools. It is important to place new documentation in the appropriate chapter in order to preserve the logical structure of the documentation set.

Source code for the three chapters enumerated above are located at path_to_cgcam/cgcam/doc/source/user, path_to_cgcam/cgcam/doc/source/developer, and path_to_cgcam/cgcam/doc/source/theory. Each of these directories contains the file index.rst that holds a table of contents for that chapter. For example, the Theory Manual currently has the following index.rst contents

Theory Manual
=============
.. toctree::
   :maxdepth: 2

Governing equations                <equations.rst>
Viscous terms                      <viscous.rst>
Characteristic boundary conditions <char_bc.rst>

If you add a new section, then you should add a corresponding entry to the index.rst file. Each section should be in a separate file with the rst extension. In many cases you can use existing documentation pages as a template for structure and syntax. You can also refer to the links at the top of this section for detailed references on reStructuredText syntax.

Once you have finished writing documentation source, build the html and view the results as explained in Section Building the documentation. Also remember to use git add new_file1, new_file2, etc. in order to add any new files to the repository.