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