Grundlegende Konzepte

Im Mittelpunkt jeder Dokumentation steht das erfassen von Gedanken, Ideen, Erkenntissen. Für die Strukturierung des Wissens bedient man sich einer Auszeichnungssprache. Sphinx bietet dafür eine Punktnotation, in der zwei Konzepte bessonders oft vorkommen:

  • Direktiven

  • Rollen

Direktiven

../_images/direktive.png

Beispiel

Das Einbinden einer Bilddatei:

.. image:: ./images/direktive.png
   :width: 300px

Rollen

Es handelt sich um semantisches Markup, das von der Standard-Auszeichnung (Default) abweichend, das Verhalten ändert.

../_images/role.png

Beispiel: Tastenkürzel

Aus normalen Buchstaben wird ein Tastendruckbeispiel:

:kbd:`C-x`, :kbd:`C-f`

C-x, C-f

Beispiel: selbstdefinierte Farben

Der Name der Rolle (»role« )wird als css-Klasse gespeichert und das gewünschte css muss vorher lokal oder zentral definiert werden.

.. role:: rot
.. role:: blau

Das wird  :rot:`rot gefärbt`, gefolgt von :blau:`blau gefärbt`.

Das wird rot gefärbt, gefolgt von blau gefärbt.

Das daszugehörige CSS

Lokal als raw-Block am Anfang der gleichen Datei.

.. raw:: html

   <style>

   .rot {
      color: red;
   }

   .blau {
      color: blue;
   }
   </style>

Fehlerquellen

Note

Nicht korrekt eingerückte Textpassagen!

  • Prüfen Sie bitte immer erst die Einrückung, für die verwendete Direktive.

  • Negative Einrückung hebt die Wirkung der vorherigen Direktive wieder auf.