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 (€)

menuselection

Dient dazu, um die Menünavigation im Administrationsbereich zu verdeutlichen.
Schreibweise: :menuselection:`Stammdaten --> Grundeinstellung`
Ausgabe: Stammdaten ‣ Grundeinstellung

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

db

Datenbanktabellen und -spalten werden mit einem eigens dafür erstellten Inline Markup gekennzeichnet.
Schreibweise: :db:`oxarticles`
Ausgabe: oxarticles

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