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.
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.
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.
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:
docs/pages/developer_manual
docs/pages/user_manual
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.
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
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 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
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.
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) |