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

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