reStructuredText
reStructuredText (a.k.a. reST or RST) is an enhanced markdown with additional syntax for complex documents.
It's mainly used in documentation as an alternative to Markdown. It's quite used with the documentation generator "sphinx" 🦁 and the well-known readthedocs 📚 theme. More information here.
What you can do in RST that you can't do in Markdown:
- 👉 Write LaTeX (math formulas...)
- 👉 Generate UML diagrams (plantuml)
- 👉 Generate Plots (graphviz, matplotlib)
➡️ See the official documentation/QuickRef.
Basics
Titles
Titles are text underlined, or over- and underlined with symbols. Any non-alphanumeric characters can be used as long as the syntax is consistent, and they are longer than the text. Two examples:
Document Title
=================
Section Title
-----------------
Subsection Title
^^^^^^^^^^^^^^^^^^^
Subsubsection Title
""""""""""""""""""""
Paragraph Title
***************
Subparagraph Title
++++++++++++++++++
###########
PART TITLE
###########
****************
Chapter Title
****************
Section Title
===============
Subsection Title
-----------------
Subsubsection Title
^^^^^^^^^^^^^^^^^^^^^
Paragraph Title
"""""""""""""""""""
Paragraph
This is a
paragraph.
Here is another paragraph
with **text in bold** and
text in *italic*.
| One Line
| Another Line
This is a paragraph.
Here is another paragraph with text in bold and text in italic.
One Line
Another Line
Links and Images
.. image:: example.png
:alt: alt message
:align: center
:width: 100%
:height: 100
:target: URL_ON_CLICK
Link: `link text <https://example.com>`_
DownloadLink: :download:`name <relative/path/to/file>`
ReusableLink: `reusable`_
.. _reusable: SOME_URL
Lists
* unordered list item
* unordered list item
+ unordered list item
+ \
unordered list item
- unordered list item
- unordered list item
1. ordered list item
2. ordered list item
a. ordered list item
b. ordered list item
#. auto ordered list item
#. auto ordered list item
Intermediate
Comments
.. this is a comment
Notices/Alerts
You may add a note, warning, hint, or an important notice to your documentation. For instance, for a hint:
.. hint::
some hint here.
Side notes/references
Side notes for a word such as xxx [#1]_ are usually
shown at the bottom of the page.
.. [#1] explain the word
➡️ You don't have to use numbers, you can use any value you want.
You can reference a section by adding a tag before the header.
.. _some_tag:
some section
===============
[...] :ref:`some_tag` [...]
Code Blocks
We can insert inline code within a text, or use a code block.
:code:`some inline code here`
.. code-block:: language
// Some code here
.. literalinclude:: configuration.json
:language: JSON
Classes and methods
You can document classes/methods/attributes using the syntax below. Note that methods or other directives can be used outside a class.
.. class:: ClassName
description...
.. method:: some_method(arg)
description...
:param arg: description...
:type arg: str
:return: description...
:rtype: bool
.. attribute:: some_attribute
description...
:type: str
Advanced
Math
Some inline latex formula :math:`a \gt b`.
.. math::
\text{some block-level latex formula.}
Plots
You can use Graphviz diagrams:
.. graphviz::
digraph {
size="10,8";
rankdir="LR";
"Bourse" -> "Opéra" [ label="5" ];
a [style=filled,color=red];
a -> b [arrowhead = none];
}
UML
Refer to PlantUML for the syntax.
.. uml::
@startuml
class User {
{field} <u>ID
{field} name
{field} first_name
{field} address
{field} ∗ email
{field} cellphone
}
@enduml
Tables
Tables are a pain to write. You need the number of equals (=) below the title of the column to be higher than any value inside the table.
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
👉 use \ to render an empty cell.
👉 A trick to avoid increasing the column size:
===== ======= =======
... ... ...
===== ======= =======
... some False
\ long \
\ content \
XXX YYY ZZZ
... ... ...
===== ======= =======
👻 To-do 👻
Stuff that I found, but never read/used yet.