Building the 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/). 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

Sphinx supports building HTML and PDF versions of the manual. For the HTML version, only Sphinx is required. Creating the PDF manual requires a LaTeX (pdflatex) installation in addition to Sphinx.

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()
  

  charmci can also be specified 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

TODO

Footnotes

TODO

Syntax highlighting for CI files

To add a new keyword or update how the syntax in CI files are highlighted, a pull request should be submitted to Pygments (https://github.com/pygments/pygments).

TODOs

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