RST (reStructured Text)

Headings

h1
==

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam.


h2
--

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam.


h3
~~

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam.


h4
^^

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam.


h5
''

Inhaltsverzeichnis

.. toctree::
   :maxdepth: 2
   :caption: Sektionsüberschrift:

   file1
   file2

Text

Einfacher Text mit 2 Absätzen:

Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

Duis autem vel eum iriure dolor in hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at vero eros et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.

Zeilenumbrüche erzwingen:

| These lines are
| broken exactly like in
| the source.

Formatierung:

**bold**
*italic kursiv*
:strike:`und das hier ist durchgestrichen (strikethrough)`

Das hier ist eine fettgedruckte Zeile. Ideal für Frage
   Und dieser Absatz ist eingerückt. Ideal für eine Antwort

Collapse/Einklappen von viel Text:

.. collapse:: Initiale Migration

    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
    tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
    quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
    consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse
    cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
    proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Information nur für den internen Gebrauch

.. only:: internal

    Any type of content here, including headings etc.

only-Direktiven sind Boolesche Ausdrücke und werden nur gerendert, wenn sie sich zu True auswerten lassen, was sich über die Kommandozeile per -t tagname beeinflussen lässt. Um obigen only-Abschnitt also explizit zu rendern, Sphinx wie folgt aufrufen: sphinx-build -b html -t internal source build

Siehe auch https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html

Horizontal line

----------

Listen

Falls zwischen zwei Listen nur eine Leerzeile steht, werden sie als eine Liste interpretiert.

Bulleted List:

* This is a bulleted list.

* Next line.
* | It has two items, the second
  | item uses two lines. (note the indentation)

  * Unterpunkt, nested list

* `Git`_ (version >=2.17.0)

Numbered List:

1. This is a numbered list.
2. It has two items too.
4. Next line

#. This is a numbered list.
#. It has two items.

Keyboard-Shortcuts

:kbd:`Shift` + :kbd:`Ctrl` + :kbd:`n`

Bilder, Logos

Ist das Bild zu gross, wird es mit der Angabe „scale“ klickbar und öffnet sich im neuen Tab.

.. image:: ../../../assets/img/nano.png
    :scale: 35%

Figure are like images but with a caption:

.. figure:: ../../../assets/img/nano.png
    :align: center
    :alt: alternate text
    :figclass: align-center
    :height: 100px
    :scale: 35%
    :target: https://www.example.com
    :width: 200px

Inline-Images erzeugt man mittels Substitutions:

Text |rss-icon| Text

.. |rss-icon| image:: ../../assets/icons/rss.png
    :target: https://blog.linuxfabrik.ch/blog/atom.xml

Hinweisboxen

Auch „Admonitions“ genannt.

Rot:

.. danger::

    Gefahr

.. error::

    Fehler

Orange:

.. attention::

    Achtung

.. caution::

    Vorsicht

.. warning::

    Warnung

Grün:

.. hint::

    Hinweis

.. important::

    Wichtig

.. tipp::

    Tipp

.. admonition:: And, by the way...

    Allgemeine Admonition mit Titel "And, by the way...". Werden im Stil einer Bemerkung angezeigt.

Blau:

.. note::

    Bemerkung

.. seealso::

    Siehe auch

Tabellen

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

CSV-Tabellen auf Basis einer Datei (siehe auch https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table):

.. csv-table::
    :file: Workshop-Massnahmen 2020-11-17.csv
    :widths: 30, 70
    :header-rows: 1
    :stub-columns: 1
    :delim: ;

Inline-CSV-Tabellen:

.. csv-table::
    :header-rows: 1
    :widths: auto

    a, b, c, "d, e"
    1, 2, 3, 4

Source-Code

Inline-Code:

Currently we are using ``Django 1.11.x`` and this version of Django ...

Code-Block, in dem gar nichts interpretiert wird, also auch keine rst-Angaben, wird mit zwei Doppelpunkten abgeschlossen (Literal Block)

Anschliessend das hier ausführen::

    git clone --recurse-submodules https://github.com/readthedocs/readthedocs.org.git
    cd readthedocs.org

Echter Code-Block:

.. code-block:: bash

    yum info man

.. code-block:: python
    :caption: Code Blocks can have captions.
    :linenos:
    :emphasize-lines: 3,5

    def some_function():
        interesting = False
        print 'This line is highlighted.'
        print 'This one is not...'
        print '...but this one is.'

Für conf-Dateien:

.. code-block:: text
    :caption: /etc/samba/smb.conf
    :linenos:

    Lorem ipsum

Externen Source-Code einbinden:

.. literalinclude:: ../../test/__init__.py
    :caption: Caption
    :language: python
    :linenos:
    :lines: 11-26

Tabs

.. tabs::

    .. tab:: RHEL 7

        Apples are green, or sometimes red.

    .. tab:: RHEL 8

        Pears are green.

    .. code-tab:: c

        int main(const int argc, const char **argv) {
            return 0;
        }

Tabs können gruppiert werden, das heisst, die Auswahl innerhalb der Gruppe ist synchronisiert. Wenn also der „RHEL 8“-Tab angewählt wird, werden alle „RHEL 8“-Tabs auf der aktuellen Seite geöffnet.

.. tabs::

    .. group-tab:: RHEL 7

        Apples are green, or sometimes red.

    .. group-tab:: RHEL 8

        Pears are green.

.. tabs::

    .. group-tab:: RHEL 7

        Apples are green, or sometimes red (2).

    .. group-tab:: RHEL 8

        Pears are green (2).

Siehe https://github.com/djungelorm/sphinx-tabs

Sphinx-Toolbox

Siehe https://sphinx-toolbox.readthedocs.io/en/latest/.

Index

Indizes

.. index::
    single: Programming languages
    single: Compiling
    single: Source code

Sonstiges

Hier steht eine Fussnote. [#]_

.. [#] Fussnoten-Hinweis
.. |date| date::

Built on |date|

Content einbinden: The directive argument is the path to the file to be included, relative to the document containing the directive.

.. include:: path/to/firewalld.rst
    :start-after: e8803a48-3ef5-4327-8742-135c834621d9
    :end-before: e3538190-06ab-4ff0-b508-a46f8d989065

    Include paths are relative to the file in the document project, not the file in shared content.