Sphinx Documentation Style Guide

This style guide provides best-practices for writing the Truchas Sphinx documentation. We encourage documentation authors to follow this guide to ensure the quality and consistency of all Truchas documentation.

Authors

Every RST document should include the author near the top of the document. This is done with the sectionauthor directive.

.. sectionauthor:: name <email>

Headings

reStructuredText does not assign heading levels to particular characters. Instead, heading levels are determined by the order in which they appear. For example, the first heading style creates a top level heading, and any further instances of that heading style also creates top level heading.

For consistency, we use the following succession of headings.

Page Title
==========

Heading 1
---------

Heading 2
+++++++++

Heading 3
^^^^^^^^^

Heading 4
~~~~~~~~~

Figures

Single Figure

When placing a single centered figure with no text wrapping around it, use a figwidth of at most 90%. This provides a visual distinction between the text and the figure. The following code block produces the figure below it.

.. figure:: https://via.placeholder.com/800x600
   :figwidth: 90%
   :align: center

   This is a caption for the figure.
https://via.placeholder.com/800x600

This is a caption for the figure.

Notice how the figure has some padding to its right and left that distinguishes it from the text before and after it. This padding is not part of the CSS to prevent excessive white space around figures that have text wrapping around them.

Side-by-Side Figures

Placing figures side-by-side in reStructuredText can be tricky. The best method we’ve found so far is to put the figures in a table. We use the list-table directive when each figure has its own caption, and the generic table directive when a caption is shared between figures.

Individual Captions

The list-table directive is useful when each figure has its own caption. For example, the following code produces the figures below it.

.. list-table::
   :align: center

   * - .. figure:: https://via.placeholder.com/400x300
          :width: 100%
          :align: center

          This is the caption.

     - .. figure:: https://via.placeholder.com/400x300
          :width: 100%
          :align: center

          This is the caption.
https://via.placeholder.com/400x300

This is the caption.
https://via.placeholder.com/400x300

This is the caption.

Shared Captions

The list-table syntax does not allow multi-column cells, so we instead use the more general table directive. Due to how tables are parsed, however, this means that images must be included indirectly through a substitution.

The following code block shows how to implement a caption spanning multiple images.

.. |image1| image:: https://via.placeholder.com/300x500
   :width: 100%
   :align: middle

.. |image2| image:: https://via.placeholder.com/300x500
   :width: 100%
   :align: middle

.. |image3| image:: https://via.placeholder.com/300x500
   :width: 100%
   :align: middle

.. table::
   :align: center

   +------------+------------+------------+
   |  |image1|  |  |image2|  |  |image3|  |
   +------------+------------+------------+
   | This caption spans all the images.   |
   | It describes the first image (left), |
   | the second image (center), and the   |
   | third image (right).                 |
   +--------------------------------------+

image1

image2

image3

This caption spans all the images. It describes the first image (left), the second image (center), and the third image (right).

Namelists

When describing a namelist and its parameters, use the following format. The exact heading level is not important, as long as the parameters are sub-headings of the namelist.

EXAMPLE Namelist
----------------

PARAMETER_1
+++++++++++
Short description of parameter 1.

.. namelist_parameter::
   :type: INTEGER
   :domain: parameter_1 >= 0
   :default: parameter_1 = 1

A more in-depth description of parameter 1. This can include any content
(e.g. images, math, code blocks) and is left to the author's discretion.

For examples of how namelists are described using this format, see the PATCHES namelist documentation.

Namelist Parameter Directive

When describing a namelist parameter, the ‘namelist_parameter’ directive should be used after the short description. This custom directive is provided by the Truchas Sphinx build.

The directive inserts an element of the nml-param class, ensuring that all namelist parameters are styled consistently throughout the documentation.

The directive takes three mandatory options:

  1. :type: the Fortran type of the namelist parameter

  2. :domain: the set of valid values for the parameter

  3. :default: the default value if the parameter is not specified

The following code block produces the namelist parameter element below it.

.. namelist_parameter::
   :type: INTEGER
   :domain: parameter_1 >= 0
   :default: parameter_1 = 1

Type: INTEGER

Domain: parameter_1 >= 0

Default: parameter_1 = 1

Inline Fortran Code

The Truchas Sphinx build provides a special ‘fortran’ role for writing inline Fortran code. For example, the following RST code

:fortran:`integer :: x`

produces the inline Fortran code integer :: x.

Other Tips

Math default role

For documents with a lot of inline math, you can set the default role to math by adding the line

.. default-role:: math

to the top of the document. Inline math can then be delimited by backticks (`) without explicitly specifying the :math: role. For example, the line

The sum of the first :math:`n` natural numbers is given by :math:`n(n+1)/2`.

simplifies to

The sum of the first `n` natural numbers is given by `n(n+1)/2`.