=========================
RST and Sphinx Cheatsheet
=========================
In this page you will get a quick overview about the most used syntax.
.. contents:: :local:
Table of content
================
To include a table of content of all title in a page use
.. code-block:: ReST
.. contents:: :local:
Titles
======
The lines have to be as long or longer than the text.
.. code-block:: ReST
=============
Section Title
=============
Titles
======
Paragraph
---------
Sub-Pragraph
^^^^^^^^^^^^
Markup
======
+----------------------------------------------------------+------------------------------------------------+
| :: | |
| | |
| *emphasis* | *emphasis* |
+----------------------------------------------------------+------------------------------------------------+
| :: | |
| | |
| **strong emphasis** | **strong emphasis** |
+----------------------------------------------------------+------------------------------------------------+
| :: | The rendering and meaning of interpreted text |
| | is domain- or application-dependent. |
| `interpreted text` | |
+----------------------------------------------------------+------------------------------------------------+
| :: | |
| | |
| ``inline literal`` | ``inline literal`` |
+----------------------------------------------------------+------------------------------------------------+
| :: | |
| | |
| :markup: | :markup: |
+----------------------------------------------------------+------------------------------------------------+
| :: | |
| | |
| > quote markup | > quote markup |
| | |
+----------------------------------------------------------+------------------------------------------------+
Links
=====
External Links
--------------
Internet
^^^^^^^^
.. code-block:: ReST
`python `_
``_
http://www.python.org/
`python `_
``_
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:
.. code-block:: ReST
.. _python: http://www.python.org/
and use like this:
.. code-block:: ReST
`python`_
You can equally create **anonymous hyperlink** and avoid `Duplicate explicit target name` warning by adding double
underscore at the end:
.. code-block:: ReST
`python `__
Other Sphinx Pages
^^^^^^^^^^^^^^^^^^
* absolute link from root
:doc:`/about/index`
* relative link from document location
:doc:`../../about/index`
.. code-block:: ReST
* 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 :ref:`writing/rst/cheatsheet:Internal References`.
In the page to be jumped to add ``.. _ref_name:``, and then you can:
.. code-block:: ReST
:ref:`ref_name`
:ref:`link title`
Like so:
* :ref:`sphinx-doc`
* :ref:`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.
.. code-block:: ReST
:ref:`Displayname `
.. code-block:: ReST
:ref:`Back to top `
:ref:`rst/cheatsheet:Images`
:ref:`Back to top `
:ref:`writing/rst/cheatsheet:Images`
.. _ref-point:
Internal References
^^^^^^^^^^^^^^^^^^^
In any place of the document a reference point can be inserted and later refered to.
.. code-block:: ReST
.. _ref-point:
see :ref:`ref-point`
see :ref:`ref-point`
Repo Links
^^^^^^^^^^
The plugin ``'sphinx.ext.extlinks`` allows creating shortcuts.
.. code-block:: python
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),
}
.. code-block:: ReST
:spl-docs-folder:`link to repo folder `
:spl-docs-file:`link to repo file `
:spl-docs-file-raw:`link to repo file open directly in raw `
:spl-docs-folder:`link to repo folder `
:spl-docs-file:`link to repo file `
:spl-docs-file-raw:`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:``
.. code:: ReST
:download:`../../img/spl.svg`
:download:`SPL Logo <../../img/spl.svg>`
:download:`../../img/spl.svg`
:download:`SPL Logo <../../img/spl.svg>`
Images
======
Images can be included with the ``figure`` directive. The path can be either absolut or relative
.. code-block:: ReST
:caption: Absolute image path from root folder
.. figure:: /img/logo.*
.. figure:: /img/logo.*
.. code-block:: ReST
:caption: Relative image path from current file folder
.. figure:: img/rst-logo.*
.. figure:: img/rst-logo.*
:width: 20%
.. 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
---------------
.. code-block:: ReST
.. 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
.. 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
Inline Images
----------------
For inline images to work, a substitution needs to be made
.. code-block:: ReST
.. |icon| image:: /img/logo.*
After that the image |icon| can be integrated inline.
.. |icon| image:: /img/logo.*
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
#. auto enumerated list item 1
#. auto enumerated list item 1
#. auto enumerated list item 1
#. auto enumerated list item 1
3. enumerated list start with item 3
#. auto enumerated list item 4
#. auto enumerated list item 5
#. auto enumerated list item 6
Tables
======
.. code-block:: ReST
.. 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
.. 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
.. code-block:: ReST
+------------+------------+-----------+
| 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 | - Cells |
+------------+ span rows. | - contain |
| body row 4 | | - blocks. |
+------------+------------+-----------+
.. code-block:: ReST
===== ===== ======
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
===== ===== ======
.. code-block:: ReST
.. table:: Table caption
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
===== ===== ======
.. table:: Table caption
===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
===== ===== ======
.. note::
flat-table need *linuxdoc* pip3 package and *linuxdoc.rstFlatTable* Sphinx extension.
.. code-block:: ReST
.. 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:: 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
- ..
Code
====
.. code-block:: ReST
.. code-block:: python
import antigravity
def main():
antigravity.fly()
if __name__=='__main__':
main()
.. code-block:: python
import antigravity
def main():
antigravity.fly()
if __name__=='__main__':
main()
.. code-block:: ReST
.. code-block:: python
:linenos:
:caption: Code Blocks can have captions.
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-block:: ReST
.. code-block:: python
:linenos:
:lineno-start: 10
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()
Infoboxes
=========
.. code-block:: ReST
.. note::
This is a Note Box
.. note::
This is a Note Box
.. code-block:: ReST
.. warning::
This is a Warning Box
.. warning::
This is a Warning Box
.. code-block:: ReST
.. important::
This is a Important Box
.. important::
This is a Important Box
.. code-block:: ReST
.. seealso::
This is a See Also Box
.. seealso::
This is a See Also Box
Special Formatting
==================
.. code-block:: ReST
.. versionadded:: 2.5
The *spam* parameter.
.. versionchanged:: 2.5
Feature description
.. deprecated:: 3.1
Use :func:`spam` instead.
.. versionadded:: 2.5
The *spam* parameter.
.. versionchanged:: 2.5
Feature description
.. deprecated:: 3.1
Use :func:`spam` instead.
Math
====
.. code-block:: ReST
Inline math :math:`a^2 + b^2 = c^2`.
Inline math :math:`a^2 + b^2 = c^2`.
.. code-block:: ReST
.. math::
f(x) &= x^2\\
g(x) &= \frac{1}{x}\\
F(x) &= \int^a_b \frac{1}{3}x^3
.. math::
f(x) &= x^2\\
g(x) &= \frac{1}{x}\\
F(x) &= \int^a_b \frac{1}{3}x^3
Exclude
=======
In order to exclude some parts for a certain output use the ``.. only:: output`` directive.
.. code-block:: ReST
.. only:: html
.. only:: draft
.. only:: latex
.. only:: html or draft or latex
.. only:: html and draft
.. important::
This is needed for the all the :ref:`writing/rst/cheatsheet:Wavedrom` code
GraphViz
========
Get more samples herer: https://graphviz.gitlab.io/gallery/
.. code-block:: ReST
.. graphviz::
digraph foo {
"bar" -> "baz";
}
.. graphviz::
digraph foo {
"bar" -> "baz";
}
.. code-block:: ReST
.. 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)" ];
}
.. 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:
.. code-block:: javascript
.. 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:
.. only:: html or draft
.. 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' },
]}
.. 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:
.. code-block:: javascript
{"reg":[
{"bits": 8, "name": "things"},
{"bits": 2, "name": "stuff" },
{"bits": 6},
],
"config": { "bits":16,"lanes":1 }
}
.. only:: html or draft
.. wavedrom::
{"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/
.. code-block:: ReST
.. 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::
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
}
.. code-block:: ReST
.. uml::
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
.. uml::
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response
Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
.. code-block:: ReST
.. 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
.. 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.
.. code-block:: ReST
.. 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:
.. code-block:: ReST
.. todolist::
See :ref:`about/index:About`
Icons
=====
One can add font-awesome icons like this: :fa:`check`
.. code-block:: ReST
:fa:`check`
Find your icons at https://fontawesome.com/v4.7.0/icons/.
Buttons
=======
.. code-block:: rst
.. 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: #
.. 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
======
.. code-block:: rst
.. 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
.. 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
Thanks to `sphinx-panels `_ extension.
Tags
====
For each page corresponding tags should be used, see :doc:`/about/tags` for all currently used tags.
.. code-block:: rst
:tag:`RST`
:tag:`ReST`
:tag:`Sphinx`
:tag:`ReST`
:tag:`RST`
:tag:`Sphinx`