Schreibkonventionen¶
Die OXID eSales Dokumentation wird in reStructuredText (reST), einer einfachen und robusten Auszeichnungssprache, geschrieben. Das erlaubt eine einheitliche Formatierung und das Generieren der Dokumentation in unterschiedlichen Ausgabeformaten, wie beispielsweise HTML oder PDF. Die Grundlagen der Textauszeichnung sind in der Sphinx Documentation beschrieben: reStructuredText Primer.
Für die Überschriften in einem Dokument, deren Auszeichnung beliebig sein kann, solange die Hierarchie eingehalten wird, haben wir folgende Festlegung getroffen: Überschrift 1 verwendet das Gleichheitszeichen (=) als Unterstreichung, Überschrift 2 den Bindestrich (-). Für Überschrift 3 ist das Caret-Zeichen (^) und für Überschrift 4 das doppelte Anführungszeichen (”) vorgesehen.
In der OXID eSales Dokumentation werden darüber hinaus sogenannte Inline Markups verwendet, um typische Textstellen zu kennzeichnen.
guilabel¶
Wird für Steuerelemente, wie beispielsweise Eingabefelder, Kontrollkästchen oder Auswahllisten, verwendet.
Schreibweise: :guilabel:`Preis (€)`
Ausgabe: Preis (€)
file¶
Dateinamen und Verzeichnisse werden mit diesem Inline Markup gekennzeichnet.
Schreibweise: :file:`config.inc.php`
Ausgabe: config.inc.php
command¶
Wird für Kommandos verwendet, die beispielsweise in einer Konsole eingegeben werden.
Schreibweise: :command:`cd oxideshop/source/tmp/smarty`
Ausgabe: cd oxideshop/source/tmp/smarty
Vorallem in der Entwicklerdokumentation wird eine Auszeichnung für Quellcode benötigt.
Quellcode¶
Quellcode, Klassen, Funktionen und URLs im Fließtext stehen zwischen doppelten Backticks.
Schreibweise: ``www.ihreshopurl.de``
Ausgabe: www.ihreshopurl.de
Für zusammenhängende Blöcke von Quellcode wird die folgende Schreibweise verwendet.
.. code:: bash
rm -r c:/docs/build-6
sphinx-build ./ c:/docs/build-6
Ausgabe:
rm -r c:/docs/build-6
sphinx-build ./ c:/docs/build-6