reST cheat sheet¶

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

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.

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$

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:

Example:

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


Result: Download the file link-title

Videos¶

This is how you can embed videos:

.. raw:: html

<center>
</center>

You can download the movie :download:here </downloads/burning_isooctane.mp4>.


You must include a have a download link to the video file, otherwise the video will not be copied over when the documentation is built. (also, note that there is an underscore in the video controls link)

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 http://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:

Table 1 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)