Writing Documentation

GS2 uses FORD to automatically build this online documentation. There are two sorts of documentation that get built: in-source and out-of-source. This page describes how to write both sorts. All the documentation is kept in the git repository, so to share any changes you make, please follow the contributing guide. The website will get built automatically when your pull request gets merged.

In-source documentation

Special Fortran comments of the form !> are used to document procedures, variables and programs using FORD. These comments are sometimes called "docstrings". FORD can understand these comments before, after or in-line with the thing to be documented, but the preferred style in GS2 is to put the comment before the entity, like in this example:

!> This is module-level documentation, describing the overall purpose of this module.
!> Documentation comments can be over several lines.
module my_module
    implicit none

    !> Docstrings can go on derived types
    type :: my_type
        !> Docstrings can include in-line LaTeX like this: \(R\)
        real :: R_major
        !> Or as a displayed equation:
        !>   $$\frac{\partial R}{\partial \psi}$$
        real :: R_major_prime
        !> Code-formatting uses `backticks`
        integer :: n_R
    end type my_type

contains

    !> We can document functions/subroutines
    real function gradient(R, psi)
        !> In order to separate the docstring for each argument...
        real, intent(in) :: R
        !> ...it's best to have each argument on its own line
        real, intent(in) :: psi
    end function gradient

end module my_module

The FORD wiki has more documentation on how to write these docstrings. Please note that while FORD accepts !< comments after or in-line with the thing to be documented, the GS2 style is to stick to !> before and on a separate line.

For a real example, see leq and its source file leq.f90.

Out-of-source documentation

As well as the code documentation, we also have some extra documentation. The source for these pages in still kept in the GS2 git repository, and are built into the website at the same time. These extra pages are written in Markdown, with some extensions (see the Python markdown implementation). There's a short cheat sheet at the bottom of this page.

Add a new page

All the out-of-source documentation is under docs/pages. FORD converts the directory hierarchy in to a hierarchy of HTML pages. The GS2 documentation is currently organised with the following sections:

  • Developer documentation: docs/pages/developer_manual
  • User documentation: docs/pages/user_manual
  • Namelists: docs/pages/namelists

The last of these, "Namelists" is autogenerated and should not be touched manually, as your changes will get overwritten.

To add a new page, simply create a new file under the appropriate directory, and use the file extension .md. Your file must contain the following at the very top:

---
title: Page title
---

Without this metadata section, FORD will not parse the file as part of the documentation.

In this metadata section, you can also have author and date items.

Another useful feature, is put [TOC] on its own line after the metadata section. This produces a hyperlinked table of contents.

See the FORD wiki for a more detailed description.

Converting LaTeX to Markdown

The easiest way to convert LaTeX to Markdown is to use Pandoc. This nifty tool understands tons of text formats and can convert between them easily, and will get the vast majority of the heavy lifting done for you. Due to the complexities of LaTeX and the simplicity of Markdown, it may require some manual tidying up after the initial conversion.

To get started, run Pandoc:

$ pandoc --standalone --from=latex --to=gfm my_docs.tex --output docs/pages/my_docs.md

FORD is a bit fussier about the metadata section at the top, compared to what Pandoc produces, so you may need to manually adjust it.

Acceptable:

---
title: On the Electrodynamics of Moving Bodies
author: A. Einstein
---

Unacceptable:

---
title: Does the Inertia of a Body Depend upon its Energy Content?
author: 
- 'A. Einstein'
---

which is a possible output from Pandoc.

FORD can render LaTeX included in the markdown, with just a couple of gotchas. The most important one is that in-line maths must use \(...\) rather than $...$. Displayed equations can be written between $$...$$, but note that this does not number the resulting equation.

Normal \begin{equation} ... \end{equation} environments can be used to get numbered equations, along with \label{eq:something} and \eqref{eq:something} to refer to them.

This example:

To obtain the distribution function at the next time step, \(g^{n+1}\), we could combine
these equations

$$A g^{n+1} + B g^{n} = DF^{-1}Gg^{n+1} + E\phi^{n},$$

is rendered as:

To obtain the distribution function at the next time step, , we could combine these equations

while

\begin{equation}
F \phi^{n+1} = G g^{n+1}
\label{eq:QN}
\end{equation}

\eqref{eq:QN} is the quasi-neutrality equation

is rendered as

\eqref{eq:QN} is the quasi-neutrality equation

Linking to sections

Section titles within a page get converted into HTML "anchors" which can be linked to. The section names are first converted to lowercase and spaces replaced with hyphens. To link to a section, use the usual link syntax and add # in front of the converted section name.

This:

Link to [this section](#linking-to-sections)

becomes:

Link to this section

Linking to source documentation

Linking directly to the code documentation is possible using FORD's syntax, which is described here:

This:

The two linear steps \(L\) are performed by the function invert_rhs in dist_fn.fpp

is rendered as:

The two linear steps are performed by the function invert_rhs in dist_fn.fpp

Building the documentation locally

FORD can be easily installed with pip:

$ pip3 install --user ford

After installing FORD, simply run make doc. This will build the documentation under docs/html:

$ make doc

Then open docs/html/index.html in your favourite browser.

Cheat sheet

See here for a comprehensive guide to Markdown.

Here's a quick little cheat sheet:

Syntax Description
Heading # Top-level
## Section
### Sub-section
Bold **bold text**
Italic *italicised text*
Code `code`
Blockquote > Block quote
Ordered lists 1. First item
2. Second item
3. Third item
Unordered lists - First item
- Second item
- Third item
Link [title](www.example.com)
Image ![alt text](image.jpg)