Writing conventions

The OXID eSales documentation is written in reStructuredText (reST), a simple and robust markup language. This allows uniform formatting and the generation of documentation in different output formats, such as HTML or PDF. The basics of text markup are described in the Sphinx documentation: reStructuredText Primer.

The following has been determined for the headings in a document that can have any markup as long as the hierarchy is respected: Heading 1 uses the equals sign (=) as underline, and heading 2 uses the hyphen (-). The caret character (^) is used for heading 3 and the double quotation mark (”) for heading 4.

The OXID eSales documentation also uses so-called inline markups to identify typical text passages.

guilabel

Is used for control elements such as input fields, check boxes, or selection lists.
Notation: :guilabel:`Price (€)`
Output: Price (€)

menuselection

Is used to illustrate the menu navigation in the Admin panel.
Notation: :menuselection:`Master Settings --> Core Settings`
Output: Master Settings ‣ Core Settings

file

This inline markup is used for file names and directories.
Notation: :file:`config.inc.php`
Output: config.inc.php

command

Is used for commands that are entered in a console, for example.
Notation: :command:`cd oxideshop/source/tmp/smarty`
Output: cd oxideshop/source/tmp/smarty

db

Database tables and columns are marked with a specially created inline markup.
Notation: :db:`oxarticles`
Output: oxarticles

Source code markup is especially required in the developer documentation.

Source code

The source code, classes, functions and URLs in the running text are put between double backticks.
Notation: ``www.ihreshopurl.de``
Output: www.ihreshopurl.de

The following notation is used for contiguous blocks of source code..

.. code:: bash

   rm -r c:/docs/build-6
   sphinx-build ./ c:/docs/build-6

Output:

rm -r c:/docs/build-6
sphinx-build ./ c:/docs/build-6