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

Links

External Links

Internet

`python <http://www.python.org/>`_
`<http://www.python.org/>`_
http://www.python.org/

python

http://www.python.org/

http://www.python.org/

If you need to use more than once the same link in the page, create a reference at the bottom of the page like that:

.. _python: http://www.python.org/

and use like this:

`python`_

You can equally create anonymous hyperlink and avoid Duplicate explicit target name warning by adding double underscore at the end:

`python <http://www.python.org/>`__

Other Sphinx Pages

• absolute link from root About

• relative link from document location About

* absolute link from root
  :doc:`/about/index`

* relative link from document location
  :doc:`../../about/index`

In order to link to another subheader in another document you need to use Internal References.

In the page to be jumped to add .. _ref_name:, and then you can:

:ref:`ref_name`
:ref:`link title<ref_name>`

Like so:

• How to use Sphinx Documentation

• Sphinx Doc Link

Internal Links

Link to Titles

Link to titles directly is done with the extension sphinx.ext.autosectionlabel.

Important

You need to add the folder_name and subfolder(s)`_name name as well as file_name without .rst extension in order to reference a section title. This avoids the duplicated label warning.

:ref:`Displayname <folder_name/subfolder_name/file_name/section_title>`

:ref:`Back to top <rst/cheatsheet:RST and Sphinx Cheatsheet>`

:ref:`rst/cheatsheet:Images`

Back to top

Images

Internal References

In any place of the document a reference point can be inserted and later refered to.

.. _ref-point:

see :ref:`ref-point`

see Internal References

Repo Links

The plugin 'sphinx.ext.extlinks allows creating shortcuts.

extlinks = {'spl-docs-repo': ('https://gitlab.hevs.ch/SPL/spl-docs/%s', None),
            'spl-docs-folder': ('https://gitlab.hevs.ch/SPL/spl-docs/tree/master/src/%s', None),
            'spl-docs-file': ('https://gitlab.hevs.ch/SPL/spl-docs/blob/master/src/%s', None),
            'spl-docs-file-raw': ('https://gitlab.hevs.ch/SPL/spl-docs/raw/master/src/%s', None),
            'constellium-docs-repo': ('https://gitlab.hevs.ch/SPL/constellium-docs/%s', None),
            'constellium-docs-repo-raw': ('https://gitlab.hevs.ch/SPL/constellium-docs/raw/master/%s', None),
            'hevslib-repo': ('https://gitlab.hevs.ch/SPL/hevslib-python/%s', None),
            'hevslib-repo-raw': ('https://gitlab.hevs.ch/SPL/hevslib-python/raw/master/%s', None),
            'pdfviewer': ('https://nbviewer.jupyter.org/%s', None),
            }

:spl-docs-folder:`link to repo folder <writing/typst/>`
:spl-docs-file:`link to repo file <writing/typst/docs/guide-to-typst.pdf>`
:spl-docs-file-raw:`link to repo file open directly in raw <writing/typst/docs/guide-to-typst.pdf>`

link to repo folder

link to repo file

link to repo file open directly in raw

Important

Especially important if the file is too big for gitlab server deployment. Via the :download: directive.

File Links

To link to a file within the Sphinx file structure use the Role :download:

:download:`../../img/spl.svg`

:download:`SPL Logo <../../img/spl.svg>`

../../img/spl.svg

SPL Logo

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.*

Relative image path from current file folder

.. figure:: img/rst-logo.*

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

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 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

3. enumerated list start with item 3

4. auto enumerated list item 4

5. auto enumerated list item 5

6. 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.

import antigravity

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

.. code-block:: python
   :linenos:
   :lineno-start: 10

   import antigravity

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

import antigravity

def main():
    antigravity.fly()
if __name__=='__main__':
    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";
   }

.. 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)" ];
   }

Wavedrom

For more information see:

• Wavedrom JSON Wiki

• Wavedrom Tutorial

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
   }

.. uml::

   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

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: #

DocumentationGitLab

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