Creating documentation

This document provides an overview of how to prepare documentation for inclusion within oomph-lib.

Setting up the documentation


  1. Within an appropriate subdirectory of the doc directory, create a directory for your documentation, e.g.
    cd doc/axisym_navier_stokes/
    mkdir spin_up
  2. Add this new directory to the parent directory's
  3. Add the entry doc/axisym_navier_stokes/spin_up to the file config/configure. ac_scripts/doc.dir_list
  4. Create a new *.txt file with the same name as the newly-created directory, e.g.
    touch spin_up.txt
    This is the "source" file from which the documentation will be generated.
  5. From an existing documentation directory, copy across the following files into the newly created directory:
    • Doxyfile
  6. In after "docfile =", add the stem of the *.txt file created in step 4, e.g.
    docfile = spin_up
  7. In Doxyfile update the (relative) path to the demo-driver directory. Two entries must be updated, one following "INPUT" and the other following "EXAMPLE_PATH". To find these, search for "../..".
  8. Return to oomph-lib's top-level directory and re-run


If your documentation is to contain figures or animations, the following subdirectories must be created within your documentation directory:

Writing the documentation

The "source" of the documentation is contained in the *.txt file (a mixture of html/doxygen markup). The title must follow the tag \mainpage and be all on one line, e.g.

\mainpage Demo problem: Spin-up of a viscous fluid

The main body of the text just follows as in a LaTeX document, with line spacings indicating paragraph breaks.


Any standard html tags can be used (for example, <hr> inserts a horizontal line). Hyperlinks are inserted in the following way:

This is illustrated in an <A HREF="../figures/my_movie.avi">animation</A>.

Note that the ".." is present in the path above because during the build process the documentation is created in subdirectories of the directory in which the source file is located. See the section Generating the documentation below for more details.

To link to the documentation of another demo driver, poisson/one_d_poisson for example, hyperlink to the index.html file within the html directory of that demo driver's documentation. Note that because the processed (html) version of the documentation you are working on will live in its own html subdirectory, it is necessary to go up three directories in order to be in oomph-lib's doc directory.

...see <A HREF="../../../poisson/one_d_poisson/html/index.html">the
Poisson tutorial</A>.


Sections are created as follows:

\section section_label This is the title of my section

Likewise, subsections are created in the following way:

\subsection subsection_label This is the title of my subsection

Any LaTeX section types can be used in this way. To link to a section within a document, use the syntax \ref section_label, as in this example:

...can be found in the section \ref theory below.


Equations are generated as in LaTeX except \f must be added before $ or [, ].

To label equations, the normal LaTeX system cannot be used. Instead, mark an equation with the tag @E[LABEL]@ and refer to it later using @R[LABEL]@, e.g.


and then later on... given by equation (@R[eqn:cont]@).


To create bullet point lists, precede each item with a -, e.g.

- First item
- Second item

To create enumerated lists, precede each item with a -#, e.g.

-# First item
-# Second item


A figure with the filename my_figure.* is inserted in the following way:


Note the space between the last character in the caption and the quotation marks. Like the equation labelling, this line is processed by the script (which is run automatically as part of the make process) and replaced with the necessary commands that tell doxygen to use the *.gif files for the html documentation and the *.eps files for the LaTeX documentation.


To insert single words of code into prose, precede the word with a \c, e.g.

The function \c FiniteElement::output(...) is used to...

To include blocks of code such as the one immediately above this line of text, use the \code environment, e.g.


To include sections of the demo code which you are documenting, e.g. the main function of, use the following syntax:

\dontinclude \skipline start_of_main
\until end of main

This only works if start_of_main exists somewhere in file, but any word(s) can be used as a start/endpoint. However, do not use dashes as targets because more recent versions of doxygen get very confused by this, so don't do

\skipline ----



Generating the documentation

Once the source file has been written, simply type make in the documentation directory to build the html and LaTeX versions, e.g.

cd doc/axisym_navier_stokes/spin_up

Two subdirectories, html and latex, are now created containing the two versions of the documentation. A *.pdf file of the LaTeX version is also placed in the current directory.

PDF file

A pdf version of this document is available.