RST and Sphinx Cheatsheet
In this page you will get a quick overview about the most used syntax.
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** |
+----------------------------------------------------------+------------------------------------------------+
| :: | 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
`python <http://www.python.org/>`_
`<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
: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:
:ref:`ref_name`
:ref:`link title<ref_name>`
Internal Links
Link to Titles
Link to titles directly is done with the extension sphinx.ext.autosectionlabel.
Info
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`
Internal References
In any place of the document a reference point can be inserted and later refered to.
.. _ref-point:
see :ref:`ref-point`
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>`
Info
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>`
Images
Images can be included with the figure directive. The path can be either absolut or relative
:caption: Absolute image path from root folder
.. figure:: /img/logo.*
:caption: Relative image path from current file folder
.. figure:: img/rst-logo.*
Info
Images should be either in png or svg format
Info
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
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.
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
.. 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
+------------+------------+-----------+
| 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. |
+------------+------------+-----------+
===== ===== ======
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
===== ===== ======
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
- ..
Code
.. code-block:: python
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
.. note::
This is a Note Box
.. warning::
This is a Warning Box
.. important::
This is a Important Box
.. seealso::
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.
Math
Inline math :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
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
Note
This is needed for the all the :ref:writing/rst/cheatsheet: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:
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' },
]}
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.
Then use the directive todolist to list all todos within the documentation:
.. todolist::
Icons
One can add font-awesome icons like this: :fa:check
: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
Thanks to sphinx-panels extension.
Tags
For each page corresponding tags should be used, see :doc:/about/tags for all currently used tags.
:tag:`RST`
:tag:`ReST`
:tag:`Sphinx`