doc/README.rst

   1 ========================================
   2 Editing and building the Charm++ manuals
   3 ========================================
   4
   5 The Charm++ manuals in this directory are written in reStructuredText (RST,
   6 http://docutils.sourceforge.net/rst.html) and meant to be built with the
   7 sphinx documentation generator (http://www.sphinx-doc.org/). Pre-built
   8 versions are available on readthedocs.io (https://charm.readthedocs.io).
   9
  10 This file describes how the documentation can be edited and built locally.
  11
  12 Building the manual
  13 ===================
  14
  15 Sphinx supports building HTML and PDF versions of the manual. For the HTML
  16 version, only Sphinx is required. Creating the PDF manual also requires pdflatex.
  17
  18 Building the HTML manual:
  19
  20 .. code-block:: bash
  21
  22   $ pip install sphinx
  23   $ cd charm/doc
  24   $ sphinx-build . html/
  25   $ firefox html/index.html
  26
  27
  28 Building the PDF manual:
  29
  30 .. code-block:: bash
  31
  32   $ pip install sphinx
  33   $ cd charm/doc
  34   $ sphinx-build -b latex . latex/
  35   $ cd latex
  36   $ make
  37   $ evince charm.pdf
  38
  39
  40 RST primer
  41 ==========
  42
  43 This section gives a brief overview of reStructuredText (RST) with the most
  44 important items for the Charm++ manual. A more comprehensive manual is
  45 available here: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html.
  46
  47 This file itself is written in RST -- take a look at the source if something is unclear.
  48
  49 Lists
  50 -----
  51
  52 - Itemized:
  53
  54   .. code-block:: none
  55
  56     - Item 1
  57     - Item 2
  58     ...
  59
  60 - Enumerated:
  61
  62   .. code-block:: none
  63
  64     #. Item 1
  65     #. Item 2
  66     ...
  67
  68 Sections
  69 --------
  70
  71 Sections get defined by underlining their title:
  72
  73 .. code-block:: none
  74
  75   Section name
  76   ============
  77
  78 - First level:  ``======``
  79 - Second level: ``-----``
  80 - Third level:  ``~~~~~~``
  81 - Fourth level: ``^^^^^``
  82 - Fifth level:  ``'''''``
  83
  84 The underline has to have the same length as the title itself.
  85
  86
  87 Code
  88 ----
  89
  90 - Inline code (similar to ``\texttt{}``):  \`\`int foo()\`\`: ``int foo();``
  91
  92   - Inline code is not syntax-highlighted.
  93
  94 - Code blocks (similar to ``\begin{alltt} .. \end{alltt}``):
  95
  96   - Code blocks have syntax highlighting via the pygments
  97     (http://pygments.org) library.
  98
  99   - Do not use the default ``::`` highlighting mode, but specify the
 100     language explicitly: ``.. code-block:: fortran`` (or ``c++``, ``none``, ...)
 101
 102     .. code-block:: none
 103
 104       .. code-block:: fortran
 105
 106         call foo()
 107         call bar()
 108
 109   Versions of pygments newer than 2.3.1 will allow specifying ``charmci`` as the
 110   language for ci-files (instead of using C++).
 111
 112 Figures
 113 -------
 114
 115 .. code-block:: none
 116
 117   .. figure:: figures/detailedsim_newer.png
 118     :name: BigNetSim1
 119     :width: 3.2in
 120
 121     Figure caption goes here.
 122
 123
 124 Tables
 125 ------
 126
 127 Code:
 128
 129 .. code-block:: none
 130
 131   .. table:: Table caption goes here.
 132     :name: tableref
 133
 134     ============= ==================== ========================================================
 135     C Field Name  Fortran Field Offset Use
 136     ============= ==================== ========================================================
 137     maxResidual   1                    If nonzero, termination criteria: magnitude of residual.
 138     maxIterations 2                    If nonzero, termination criteria: number of iterations.
 139     solverIn[8]   3-10                 Solver-specific input parameters.
 140     ============= ==================== ========================================================
 141
 142 Rendered as:
 143
 144 .. table:: Table caption goes here.
 145   :name: tableref
 146
 147   ============= ==================== ========================================================
 148   C Field Name  Fortran Field Offset Use
 149   ============= ==================== ========================================================
 150   maxResidual   1                    If nonzero, termination criteria: magnitude of residual.
 151   maxIterations 2                    If nonzero, termination criteria: number of iterations.
 152   solverIn[8]   3-10                 Solver-specific input parameters.
 153   ============= ==================== ========================================================
 154
 155 References
 156 ----------
 157
 158 Adding reference labels
 159 ~~~~~~~~~~~~~~~~~~~~~~~
 160
 161 Labels to refer to tables and figures are created by the ``:name:`` property above.
 162 Create labels for sections like this:
 163
 164 .. code-block:: none
 165
 166   .. _my-label:
 167   Section ABCD
 168   ============
 169
 170 Section ABCD can now be referenced with ``my-label`` (note the missing ``_``
 171 and ``:`` in the reference).
 172
 173
 174 Referencing labels
 175 ~~~~~~~~~~~~~~~~~~
 176
 177 - With number (best for figures & tables): ``:numref:`reference_name```
 178 - With text: ``:ref:`reference_name``` (text will be taken from referenced item automatically)
 179 - With custom text: ``:ref:`Custom text here <reference_name>```
 180
 181 Links
 182 -----
 183
 184 URLs get parsed and displayed as links automatically. For example: https://charm.cs.illinois.edu/
 185
 186 Citations
 187 ---------
 188
 189 .. code-block:: none
 190
 191   This is a reference [Ref]_ .
 192
 193   .. [Ref] Paper or article reference, URL, ...
 194
 195 Footnotes
 196 ---------
 197
 198 .. code-block:: none
 199
 200   This text has a footnote [1]_
 201
 202   .. [1] Text of the footnote.