reST cheat sheet
****************

See also:

  This document is by no means an exhaustive guide to **Sphinx** and
  **reStructuredText (reST)**. Additional resources:

  * Our wiki page

  * Sphinx website

  * reStructuredText primer (a lot of stuff in this document is taken
    from here)

  * reStructuredText doc

  * super useful page (or https://github.com/marczz/rest-sphinx-
    memo/blob/master/source/ReST.rst)

Our documentation is a **collection of several Sphinx projects** (ADF,
AMS, Band, Tutorials,...). All the projects import "global_conf.py"
from the local "conf.py".


External links
==============

Important:

  For cross-links between different SCM documentation projects, see
  Inter-project links.

This "`Search engine <https://duckduckgo.com>`__" creates an external
link like this: Search engine

This "`<https://duckduckgo.com>`__" creates an external link like
this: https://duckduckgo.com


Internal links
==============

For internal links standard reST **labels** are used. The are two ways
of doing this:

* If you place a label directly before a section title, you can
  reference to it with ":ref:`label-name`". For example.

     .. _label-name:

     Section to cross-reference
     --------------------------

     This is the text of the section.

     It refers to the section itself, see :ref:`label-name`.

* Labels that aren’t placed before a section title can still be
  referenced, but you must give the link an explicit title, using this
  syntax

     .. _label-name:

     Some random text, see :ref:`link title <label-name>`.


Inter-project links
===================


Option 1: intersphinx to refer to labels
----------------------------------------

If you use intersphinx then you can refer to labels in other docs,
just as for Internal links.

See for example how this works in the Workflows conf.py:

   # -*- coding: utf-8 -*-

   from global_conf import *

   project, htmlhelp_basename, latex_documents = set_project_specific_var("Workflows")

   extensions += ["sphinx.ext.autodoc", "sphinx.ext.intersphinx", "sphinx.ext.viewcode", "sphinx_copybutton"]

   # If true, the current module name will be prepended to all description
   # unit titles (such as .. function::).
   add_module_names = False


   autodoc_default_options = {"members": True, "private-members": True, "special-members": True}
   autodoc_member_order = "bysource"
   autodoc_typehints = "none"

   intersphinx_mapping = {
       "AMS": ("../AMS/", "../build/AMS/objects.inv"),
       "MLPotential": ("../MLPotential/", "../build/MLPotential/objects.inv"),
       "Tutorials": ("../Tutorials/", "../build/Tutorials/objects.inv"),
       "params": ("../params/", "../build/params/objects.inv"),
   }

   intersphinx_disabled_reftypes = ["*"]


   def setup(app):
       disable_intersphinx_for_text_builder(app)
       enable_intersphinx_text_fallback(app)

Note the extension "sphinx.ext.intersphinx" and the
"intersphinx_mapping" dictionary, which specifies the AMS objects.inv
file which contains all labels and the corresponding targets. This
makes it possible to refer the labels defined in the AMS docs from
inside the Workflows docs. For example,
":external+AMS:ref:`chemtrayzer2`".

For this to work, the dependency must be set in "userdoc/build_doc.py"
on the corresponding "DocumentationTarget" (in "TARGET_CATALOG"), for
example via the "dependencies=(...)" tuple. The build script then
ensures that dependent manuals are built first. For links that would
require cyclic dependencies (for example linking both ways between two
manuals), use **Option 2: external links with relative paths** below.


Option 2: external links with relative paths
--------------------------------------------

For links from one documentation project to another one (e.g. links
from the AMS manual to the Tutorials or vice versa) use **external
links with relative paths**. To make a link from page_A (in project_A)
to page_B (in project_B) you should use the relative path from page_A
to page_B.

For example, to make a link from this page to a page in the Tutorials:

   Link to a page in the Tutorials: `AMS Tutorial <../Tutorials/AMS/ZN-PES-Scan_TST.html>`__

Do **not** use an absolute link starting with "www.SCM.com/doc" for
inter-project links.


Citations / References
======================

For citations we use footnotes.

**Example:**

   Cite a paper here [#ref1]_ and another one here [#ref2]_.

   .. Then, at the bottom of the page:

   .. [#ref1] \G. te Velde, F.M. Bickelhaupt, E.J. Baerends, C. Fonseca Guerra, S.J.A. van Gisbergen, J.G. Snijders, T. Ziegler, *Chemistry with ADF*, `Journal of Computational Chemistry 22, 931 (2001) <https://doi.org/10.1002/jcc.1056>`__

   .. [#ref2] \E. J. Baerends and P. Ros, *Evaluation of the LCAO Hartree-Fock-Slater method: Applications to transition-metal complexes*, `International Journal of Quantum Chemistry 14, S12, 169 (1978) <https://doi.org/10.1002/qua.560140814>`__

**Result:** Cite a paper here [1] and another one here [2].

Note:

  In the example above, the "\" before "G. te Velde" at the beginning
  of the line is to prevent sphinx from interpreting "G." that as an
  enumerated list!


Equations
=========

For equation we use MathJax. The syntax is essentially the same as for
latex equations.

**Example:**

   The current :math:`I(V)` can be computed using the following equation:

   .. math::

     I(V) = \frac{2e}{h} \int_{-\infty}^\infty T(E,V) f(E) dE

**Result:**

The current I(V) can be computed using the following equation:

   I(V) = \frac{2e}{h} \int_{-\infty}^\infty T(E,V) f(E) dE


Unicode symbols
===============

You may optionally use unicode symbols, like this : *D* = 2 × 10⁻⁹ m²
s⁻¹. A direct band gap at the Γ point.

In vim, you can access these in insert mode using Ctrl-k (or see
":help digraphs", ":help digraph-table", and ":digraphs"). For
example:

+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k p*"                       | π                                 | asterisk = Greek letter           |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k P*"                       | Π                                 | asterisk = Greek letter           |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k -S"                       | ⁻                                 | capital S = superscript           |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k 2S"                       | ²                                 | capital S = superscript           |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k 2s"                       | ₂                                 | lowercase s = subscript           |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k DG"                       | °                                 | degree                            |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k oC"                       | ℃                                 | degree C                          |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k AO"                       | Å                                 | angstrom                          |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k ->"                       | →                                 | right arrow                       |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k <-"                       | ←                                 | left arrow                        |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k +-"                       | ±                                 | plus/minus                        |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k *X"                       | ×                                 | multiplication cross              |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k .M"                       | ·                                 | center dot                        |
+-----------------------------------+-----------------------------------+-----------------------------------+
| "CTRL-k ?2"                       | ≈                                 | approximately equal               |
+-----------------------------------+-----------------------------------+-----------------------------------+

The right arrow → is used frequently in tutorials. In vim, you can
save it to a global register, for example with ":let @r '→'". You can
then simply press "CTRL-r r" in insert mode to insert a right arrow.

You can also insert Unicode character with 4 digits, for example (in
insert mode): "CTRL-v u2248" gives ≈.


Images
======

For images we use the "figure" directive. Simple usage:

   .. figure:: Images/NEGF.png

**Example** (with some options):

   .. figure:: Images/NEGF.png
     :width: 80%
     :align: center

     Optionally, you can put your caption here.

**Result:**

   [image]Optionally, you can put your caption here.


File download
=============

**Example:**

   Download the file :download:`link-title <downloads/file.txt>`

**Result:** Download the file "link-title"


Videos
======

Place videos in a manual-local "_videos" folder (next to "conf.py").
They will be copied to "_static" in the built docs. This is how you
can embed videos:

   .. raw:: html

     <center>
       <video controls src="../_static/burning_isooctane.mp4"></video>
     </center>

     You can `download the movie <../_static/burning_isooctane.mp4>`__ if it does not play in your browser.


Index
=====

Before section titles you generally want to use many index directives
with plausible alternative names.

**Example:**

   .. index:: Excitations
   .. index:: TDDFT
   .. index:: UV/Vis
   .. index:: Other reasonable names people might search for...

   Excitations with TDDFT
   ----------------------


Tables
======

For tables I advise using "csv-table" (they are much easier to
maintain than "grid tables" and "Simple tables"). See also https://www
.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#tables.
Example:

**Example:**

   .. csv-table:: Optional title
      :header: "Animal", "Furry", "Pettability [a.u.]"

      "Cat", "Yes", 9
      "Dog", "Yes", 9
      "Naked mole rat", "No",  5

**Result:**


Optional title
^^^^^^^^^^^^^^

+-----------------------------------+-----------------------------------+-----------------------------------+
| Animal                            | Furry                             | Pettability [a.u.]                |
|===================================|===================================|===================================|
| Cat                               | Yes                               | 9.5                               |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Dog                               | Yes                               | 9.8                               |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Naked mole rat                    | No                                | 2.7                               |
+-----------------------------------+-----------------------------------+-----------------------------------+


Code and input snippets
=======================

For snippets of code or run-scripts use the "code-block" directive.

**Example:**

   Some python code:

   .. code-block:: python
     :emphasize-lines: 3,4

     def some_function():
       interesting = False
       print 'This line is highlighted.'
       print 'This one as well...'
       print '...but not this one.'

   Some ADF input block example:

   .. code-block:: none

     Excitations
       Lowest 5
       FullKernel
       OnlySing
     End

**Result:**

Some python code:

   def some_function():
     interesting = False
     print 'This line is highlighted.'
     print 'This one as well...'
     print '...but not this one.'

Some ADF input block example:

   Excitations
     Lowest 5
     FullKernel
     OnlySing
   End

[1] G. te Velde, F.M. Bickelhaupt, E.J. Baerends, C. Fonseca Guerra,
    S.J.A. van Gisbergen, J.G. Snijders, T. Ziegler, *Chemistry with
    ADF*, Journal of Computational Chemistry 22, 931 (2001)

[2] E. J. Baerends and P. Ros, *Evaluation of the LCAO Hartree-Fock-
    Slater method: Applications to transition-metal complexes*,
    International Journal of Quantum Chemistry 14, S12, 169 (1978)
