doc: README with doc build instructions & RST overview 05/4905/7
authorMatthias Diener <mdiener@illinois.edu>
Thu, 17 Jan 2019 21:41:05 +0000 (15:41 -0600)
committerRonak Buch <rabuch2@illinois.edu>
Thu, 14 Feb 2019 18:26:49 +0000 (12:26 -0600)
Change-Id: I49df52d6ff1bc0a28b5ae031abac2fe7b4d707cc

doc/README.rst [new file with mode: 0644]
doc/conf.py

diff --git a/doc/README.rst b/doc/README.rst
new file mode 100644 (file)
index 0000000..2a0340a
--- /dev/null
@@ -0,0 +1,210 @@
+========================================
+Editing and building the Charm++ manuals
+========================================
+
+The Charm++ manuals in this directory 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 file 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 also requires pdflatex.
+
+Building the HTML manual:
+
+.. code-block:: bash
+
+  $ pip install sphinx
+  $ cd charm/doc
+  $ sphinx-build . html/
+  $ firefox html/index.html
+
+
+Building the PDF manual:
+
+.. code-block:: bash
+
+  $ pip install sphinx
+  $ cd charm/doc
+  $ sphinx-build -b latex . latex/
+  $ cd latex
+  $ make
+  $ evince charm.pdf
+
+
+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.
+
+This file 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:  ``'''''``
+
+The underline has to have the same length as the title itself.
+
+
+Code
+----
+
+- Inline code (similar to ``\texttt{}``):  \`\`int foo()\`\`: ``int foo();``
+
+  - Inline code is not syntax-highlighted.
+
+- Code blocks (similar to ``\begin{alltt} .. \end{alltt}``):
+
+  - Code blocks have syntax highlighting for C++ by default, via the pygments
+    (http://pygments.org) library.
+
+  - Automatic syntax highlighting (default language: C++): ``::``
+
+    ::
+
+      ::
+
+        int foo();
+        int bar();
+
+  - Specify language: ``.. code-block:: fortran`` instead of ``::``
+
+    ::
+
+      .. code-block:: fortran
+
+        call foo()
+        call bar()
+
+  Versions of pygments newer than 2.3.1 allow specifying ``charmci`` as the
+  language for ci-files (instead of the default C++).
+
+Figures
+-------
+
+::
+
+  .. figure:: figures/detailedsim_newer.png
+    :name: BigNetSim1
+    :width: 3.2in
+
+    Figure caption goes here.
+
+
+Tables
+------
+
+Code:
+
+::
+
+  .. 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.
+    ============= ==================== ========================================================
+
+Rendered as:
+
+.. 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
+-----
+
+URLs get parsed and displayed as links automatically. For example: https://charm.cs.illinois.edu/
+
+Citations
+---------
+
+::
+
+  This is a reference [Ref]_ .
+
+  .. [Ref] Paper or article reference, URL, ...
+
+Footnotes
+---------
+
+::
+
+  This text has a footnote [1]_
+
+  .. [1] Text of the footnote.
\ No newline at end of file
index b299bfcd1cee89d7079422d60cb03d3688509464..339873eb0495128aca91e8366f5571213d25fb15 100644 (file)
@@ -63,7 +63,7 @@ language = None
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path .
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README.rst']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'