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.
Verweise und Links
URLs will automatically linked:
Visit http://127.0.0.1:8000/ in your browser to see how it looks.
URL/Link mit eigenem Text (darauf achten, dass „anonyme Links“ mit doppeltem Underscore verwendet werden, so werden Duplicate explicit target name Warnungen verhindert):
`dashboard <http://localhost:8000/dashboard/>`__.
Verweis auf ein anderes Dokument:
:doc:`path/to/other/document` (Titel des Dokuments wird übernommen)
:doc:`für weitere Informationen <path/to/other/document>`
Interne Verweise (am geschicktesten mit UUIDs arbeiten - so ist es eindeutig, und man muss sich keine Namen ausdenken):
Das ist ein :ref:`interner Verweis (benötigt eine Leerzeile bei der Definition) <b9bac35c-c97a-4305-9eeb-6a2eb8e7be84>`. Benötigt keinen führenden Underscore.
.. _b9bac35c-c97a-4305-9eeb-6a2eb8e7be84:
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).
Sphinx-Toolbox
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.