Building the manual

The RST manual

The Charm++ manuals are written in reStructuredText (RST, http://docutils.sourceforge.net/rst.html) and meant to be built with the Sphinx documentation generator (http://www.sphinx-doc.org/), version 2.4.0 or higher. Pre-built versions are available on readthedocs.io (https://charm.readthedocs.io).

This wiki describes how the documentation can be edited and built locally.

Building the manual

HTML output

$ pip install sphinx      # Only needed once.
$ cd charm/doc
$ sphinx-build . html/    # HTML output is the default.
$ firefox html/index.html

PDF output

Building the manual as a single PDF file:

$ pip install sphinx      # Only needed once.
$ cd charm/doc
$ sphinx-build -b latex . pdf/
$ cd pdf
$ make
$ evince pdf/charm.pdf

Building only a single manual (Charm++ manual in this example):

$ cd doc/charm++
$ sphinx-build -b latex -C -Dmaster_doc=manual -Dproject=Charm++  -Dnumfig=1 . latex
$ cd latex
$ make

RST primer

This section gives a brief overview of reStructuredText (RST) with the most important items for the Charm++ manual. A more comprehensive manual is available here: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html.

N.B.: This wiki entry itself is written in RST - take a look at the source if something is unclear.

Lists

• Itemized:

  - Item 1
  - Item 2
  ...
  

• Enumerated:

  #. Item 1
  #. Item 2
  ...
  

Sections

Sections get defined by underlining their title:

Section name
============

• First level: ======
• Second level: -----
• Third level: ~~~~~~
• Fourth level: ^^^^^
• Fifth level: '''''

Length of the underline has to be the same as the title itself.

Code

• Inline code (similar to \texttt{}): ``int foo()``: int foo();

• Code blocks (similar to \begin{alltt} .. \end{alltt}):

  • Automatic syntax highlighting (default language: C++): ::

  ::
  
    int foo();
    int bar();
  

  • Specify language: .. code-block:: fortran instead of ::

  .. code-block:: fortran
  
     call foo()
     call bar()
  

  N.B.: As soon as https://bitbucket.org/birkenfeld/pygments-main/pull-requests/788 is merged, we can specify charmci as the language for ci-files.

Figures

.. figure:: figures/detailedsim_newer.png
   :name: BigNetSim1
   :width: 3.2in

   Figure caption goes here.

Tables

.. table:: Table caption goes here.
   :name: tableref

   ============= ==================== ========================================================
   C Field Name  Fortran Field Offset Use
   ============= ==================== ========================================================
   maxResidual   1                    If nonzero, termination criteria: magnitude of residual.
   maxIterations 2                    If nonzero, termination criteria: number of iterations.
   solverIn[8]   3-10                 Solver-specific input parameters.
   ============= ==================== ========================================================

References

Adding reference labels

Labels to refer to tables and figures are created by the :name: property above. Create labels for sections like this:

.. _my-label:

Section ABCD
============

Section ABCD can now be referenced with my-label (note the missing _ and : in the reference).

Referencing labels

• With number (best for figures & tables): :numref:`reference_name`
• With text: :ref:`reference_name` (text will be taken from referenced item automatically)
• With custom text: :ref:`Custom text here <reference_name>`

Links

https:// etc. get parsed as links automatically.

Citations

Footnotes

TODOs

• Split each manual into multiple .rst files to simplify searching and editing.