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