RST and Sphinx Cheatsheet#

In this page you will get a quick overview about the most used syntax.

Table of content#

To include a table of content of all title in a page use

.. contents:: :local:

Titles#

The lines have to be as long or longer than the text.

=============
Section Title
=============

Titles
======

Paragraph
---------

Sub-Pragraph
^^^^^^^^^^^^

Markup#

*emphasis*

emphasis

**strong emphasis**

strong emphasis

`interpreted text`

The rendering and meaning of interpreted text is domain- or application-dependent.

``inline literal``

inline literal

:markup:
markup

> quote markup

> quote markup

Images#

Images can be included with the figure directive. The path can be either absolut or relative

Absolute image path from root folder#
.. figure:: /img/logo.*
../../_images/logo4.svg
Relative image path from current file folder#
.. figure:: img/rst-logo.*
../../_images/rst-logo.svg

Important

Images should be either in png or svg format

Important

For *.svg files the file ending needs to be changed from svg to *. That way for html svg is used and pdf or pn for the latex or pdf output.

Image Placement#

.. figure:: /img/logo.*
   :align: left
   :width: 100px

.. figure:: /img/logo.*
   :align: center
   :width: 100px

.. figure:: /img/logo.*
   :align: right
   :width: 100px

.. figure:: /img/logo.*
   :align: center
   :width: 100px
   :height: 100px
   :scale: 50 %
   :alt: this is the knowhow logo

   Caption of figure
../../_images/logo4.svg
../../_images/logo4.svg
../../_images/logo4.svg
this is the knowhow logo

Caption of figure#

Inline Images#

For inline images to work, a substitution needs to be made

.. |icon| image:: /img/logo.*

After that the image |icon| can be integrated inline.

After that the image icon can be integrated inline.

Lists#

  • item 1

    • item 1.1

    • item 1.2

  • item 2

    • item 2.1

      • item 2.1.1

  1. auto enumerated list item 1

  2. auto enumerated list item 1

  3. auto enumerated list item 1

  4. auto enumerated list item 1

  1. enumerated list start with item 3

  2. auto enumerated list item 4

  3. auto enumerated list item 5

  4. auto enumerated list item 6

Tables#

.. list-table:: Table title
   :widths: auto
   :header-rows: 1
   :stub-columns: 1

   * - Header 1
     - Header 2
     - Header 3
   * - row 1
     - column 2
     - column 3
   * - row 2
     - column 2
     - column 3
   * - row 3
     - column 2
     - column 3
Table title#

Header 1

Header 2

Header 3

row 1

column 2

column 3

row 2

column 2

column 3

row 3

column 2

column 3

+------------+------------+-----------+
| Header 1   | Header 2   | Header 3  |
+============+============+===========+
| body row 1 | column 2   | column 3  |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may  | - Cells   |
+------------+ span rows. | - contain |
| body row 4 |            | - blocks. |
+------------+------------+-----------+

Header 1

Header 2

Header 3

body row 1

column 2

column 3

body row 2

Cells may span columns.

body row 3

Cells may span rows.

  • Cells

  • contain

  • blocks.

body row 4

=====  =====  ======
Inputs     Output
------------  ------
  A      B    A or B
=====  =====  ======
False  False  False
True   False  True
False  True   True
True   True   True
=====  =====  ======

Inputs

Output

A

B

A or B

False

False

False

True

False

True

False

True

True

True

True

True

.. table:: Table caption

   =====  =====  ======
      Inputs     Output
   ------------  ------
     A      B    A or B
   =====  =====  ======
   False  False  False
   =====  =====  ======
Table caption#

Inputs

Output

A

B

A or B

False

False

False

Note

flat-table need linuxdoc pip3 package and linuxdoc.rstFlatTable Sphinx extension.

.. flat-table:: flat-table example
   :header-rows: 2
   :stub-columns: 1
   :widths: 1 1 1 1 2

   * - :rspan:`1` head / stub
   - :cspan:`3` head 1.1-4

   * - head 2.1
   - head 2.2
   - head 2.3
   - head 2.4

   * .. row body 1 / this is a comment

   - row 1
   - :rspan:`2` cell 1-3.1
   - cell 1.2
   - cell 1.3
   - cell 1.4

   * .. Comments and targets are allowed on *table-row* stage.
   .. _`row body 2`:

   - row 2
   - cell 2.2
   - :rspan:`1` :cspan:`1`
      cell 2.3 with a span over

      * col 3-4 &
      * row 2-3

   * - row 3
   - cell 3.2

   * - row 4
   - cell 4.1
   - cell 4.2
   - cell 4.3
   - cell 4.4

   * - row 5
   - cell 5.1 with automatic span to rigth end

   * - row 6
   - cell 6.1
   - ..
flat-table example#

head / stub

head 1.1-4

head 2.1

head 2.2

head 2.3

head 2.4

row 1

cell 1-3.1

cell 1.2

cell 1.3

cell 1.4

row 2

cell 2.2

cell 2.3 with a span over

  • col 3-4 &

  • row 2-3

row 3

cell 3.2

row 4

cell 4.1

cell 4.2

cell 4.3

cell 4.4

row 5

cell 5.1 with automatic span to rigth end

row 6

cell 6.1

Code#

.. code-block:: python

   import antigravity

   def main():
       antigravity.fly()
   if __name__=='__main__':
       main()
import antigravity

def main():
    antigravity.fly()
if __name__=='__main__':
    main()
.. code-block:: python
   :linenos:
   :caption: Code Blocks can have captions.

   import antigravity

   def main():
       antigravity.fly()
   if __name__=='__main__':
       main()
Code Blocks can have captions.#
1import antigravity
2
3def main():
4    antigravity.fly()
5if __name__=='__main__':
6    main()
.. code-block:: python
   :linenos:
   :lineno-start: 10

   import antigravity

   def main():
       antigravity.fly()
   if __name__=='__main__':
       main()
10import antigravity
11
12def main():
13    antigravity.fly()
14if __name__=='__main__':
15    main()

Infoboxes#

.. note::
   This is a Note Box

Note

This is a Note Box

.. warning::
   This is a Warning Box

Warning

This is a Warning Box

.. important::
   This is a Important Box

Important

This is a Important Box

.. seealso::
   This is a See Also Box

See also

This is a See Also Box

Special Formatting#

.. versionadded:: 2.5
   The *spam* parameter.

.. versionchanged:: 2.5
   Feature description

.. deprecated:: 3.1
   Use :func:`spam` instead.

New in version 2.5: The spam parameter.

Changed in version 2.5: Feature description

Deprecated since version 3.1: Use spam() instead.

Math#

Inline math :math:`a^2 + b^2 = c^2`.

Inline math \(a^2 + b^2 = c^2\).

.. math::

   f(x) &= x^2\\
   g(x) &= \frac{1}{x}\\
   F(x) &= \int^a_b \frac{1}{3}x^3
\[\begin{split}f(x) &= x^2\\ g(x) &= \frac{1}{x}\\ F(x) &= \int^a_b \frac{1}{3}x^3\end{split}\]

Exclude#

In order to exclude some parts for a certain output use the .. only:: output directive.

.. only:: html
.. only:: draft
.. only:: latex
.. only:: html or draft or latex
.. only:: html and draft

Important

This is needed for the all the Wavedrom code

GraphViz#

Get more samples herer: https://graphviz.gitlab.io/gallery/

.. graphviz::

   digraph foo {
      "bar" -> "baz";
   }
digraph foo {
   "bar" -> "baz";
}
.. graphviz::

   digraph finite_state_machine {
     rankdir=LR;
     size="8,5"
     node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
     node [shape = circle];
     LR_0 -> LR_2 [ label = "SS(B)" ];
     LR_0 -> LR_1 [ label = "SS(S)" ];
     LR_1 -> LR_3 [ label = "S($end)" ];
     LR_2 -> LR_6 [ label = "SS(b)" ];
     LR_2 -> LR_5 [ label = "SS(a)" ];
     LR_2 -> LR_4 [ label = "S(A)" ];
     LR_5 -> LR_7 [ label = "S(b)" ];
     LR_5 -> LR_5 [ label = "S(a)" ];
     LR_6 -> LR_6 [ label = "S(b)" ];
     LR_6 -> LR_5 [ label = "S(a)" ];
     LR_7 -> LR_8 [ label = "S(b)" ];
     LR_7 -> LR_5 [ label = "S(a)" ];
     LR_8 -> LR_6 [ label = "S(b)" ];
     LR_8 -> LR_5 [ label = "S(a)" ];
   }
digraph finite_state_machine {
  rankdir=LR;
  size="8,5"
  node [shape = doublecircle]; LR_0 LR_3 LR_4 LR_8;
  node [shape = circle];
  LR_0 -> LR_2 [ label = "SS(B)" ];
  LR_0 -> LR_1 [ label = "SS(S)" ];
  LR_1 -> LR_3 [ label = "S($end)" ];
  LR_2 -> LR_6 [ label = "SS(b)" ];
  LR_2 -> LR_5 [ label = "SS(a)" ];
  LR_2 -> LR_4 [ label = "S(A)" ];
  LR_5 -> LR_7 [ label = "S(b)" ];
  LR_5 -> LR_5 [ label = "S(a)" ];
  LR_6 -> LR_6 [ label = "S(b)" ];
  LR_6 -> LR_5 [ label = "S(a)" ];
  LR_7 -> LR_8 [ label = "S(b)" ];
  LR_7 -> LR_5 [ label = "S(a)" ];
  LR_8 -> LR_6 [ label = "S(b)" ];
  LR_8 -> LR_5 [ label = "S(a)" ];
}

Wavedrom#

For more information see:

Timing Diagrams#

This documentation makes use of the sphinxcontrib-wavedrom plugin, So you can specify a timing diagram, or a register description with the WaveJSON syntax like so:

.. wavedrom::

   { "signal": [
      { "name": "pclk", "wave": 'p.......' },
      { "name": "Pclk", "wave": 'P.......' },
      { "name": "nclk", "wave": 'n.......' },
      { "name": "Nclk", "wave": 'N.......' },
      {},
      { "name": 'clk0', "wave": 'phnlPHNL' },
      { "name": 'clk1', "wave": 'xhlhLHl.' },
      { "name": 'clk2', "wave": 'hpHplnLn' },
      { "name": 'clk3', "wave": 'nhNhplPl' },
      { "name": 'clk4', "wave": 'xlh.L.Hx' },
   ]}

and you get:

Note

if you want the Wavedrom diagram to be present in the pdf export, you need to use the “non relaxed” JSON dialect. long story short, no javascript code and use " arround key value (Eg. "name").

Register#

you can describe register mapping with the same syntax:

{"reg":[
  {"bits": 8, "name": "things"},
  {"bits": 2, "name": "stuff" },
  {"bits": 6},
 ],
 "config": { "bits":16,"lanes":1 }
 }

PlantUML#

This documentation makes use of the sphinxcontrib.plantuml plugin, for more information see the sphinxcontrib.plantuml plugin and the PlantUML Webpage. For a small Cheatsheet for PlantUML see https://ogom.github.io/draw_uml/plantuml/

.. uml::

   class Foo1 {
     You can use
     several lines
     ..
     as you want
     and group
     ==
     things together.
     __
     You can have as many groups
     as you want
     --
     End of class
   }

   class User {
     .. Simple Getter ..
     + getName()
     + getAddress()
     .. Some setter ..
     + setName()
     __ private data __
     int age
     -- encrypted --
     String password
   }

class Foo1 {
  You can use
  several lines
  ..
  as you want
  and group
  ==
  things together.
  __
  You can have as many groups
  as you want
  --
  End of class
}

class User {
  .. Simple Getter ..
  + getName()
  + getAddress()
  .. Some setter ..
  + setName()
  __ private data __
  int age
  -- encrypted --
  String password
}

.. uml::

   Alice -> Bob: Authentication Request
   Bob --> Alice: Authentication Response

   Alice -> Bob: Another authentication Request
   Alice <-- Bob: Another authentication Response

Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response

.. uml::

   actor actor
   agent agent
   artifact artifact
   boundary boundary
   card card
   cloud cloud
   component component
   control control
   database database
   entity entity
   file file
   folder folder
   frame frame
   interface  interface
   node node
   package package
   queue queue
   stack stack
   rectangle rectangle
   storage storage
   usecase usecase

actor actor
agent agent
artifact artifact
boundary boundary
card card
cloud cloud
component component
control control
database database
entity entity
file file
folder folder
frame frame
interface  interface
node node
package package
queue queue
stack stack
rectangle rectangle
storage storage
usecase usecase

Todo#

If the extension sphinx.ext.todo is enabled and the variable todo_include_todos is set to True in conf.py, one can use the directive todo to write a todo task for a later completion.

.. todo::

   (example) This section need to be completed.

Todo

(example) This section need to be completed.

Then use the directive todolist to list all todos within the documentation:

.. todolist::

See About

Icons#

One can add font-awesome icons like this:

:fa:`check`

Find your icons at https://fontawesome.com/v4.7.0/icons/.

Buttons#

.. button:: Documentation
   :class: btn-large-square fa fa-book btn-hover-blue
   :link: #

.. button:: GitLab
   :class: btn-large-square fa fa-gitlab btn-hover-red
   :link: #

Note

The button link opens a new browser page.

Panels#

.. panels::
   :container: container-lg pb-3
   :column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2

   panel1
   ---
   panel2
   ---
   panel3
   ---
   :column: col-lg-12 p-2

   Header
   ^^^^^^

   panel4

panel1

panel2

panel3

Header

panel4

Thanks to sphinx-panels extension.

Tags#

For each page corresponding tags should be used, see SPL Doc Tags for all currently used tags.

:tag:`RST`
:tag:`ReST`
:tag:`Sphinx`

ReST RST Sphinx