Conventions for writing developer documentation

Sections

  • Each page MUST have one page title as the only first level heading, separated by ===. Otherwise last one would be as document name in Sphinx menu.
  • Subsequent headers should be marked with ---, ^^^, """, ~~~ etc.

Good examples:

Title
=====

First level
-----------

Second level
^^^^^^^^^^^^

First level
-----------

Second level
^^^^^^^^^^^^

Third level
"""""""""""

Forth level
~~~~~~~~~~~

Bad examples:

  • Inconsistent headers:
First level
-----------

Second level
""""""""""""

Third level
^^^^^^^^^^^
  • Two titles in a page:
Title
=====

First level
-----------

Title
=====

First level
-----------

Tables

+-------------------+--------------------+
| Column 1 Heading  | Column 2 Heading   |
+===================+====================+
| Column 1 Cell 1   | Column 2 Cell1     |
+-------------------+--------------------+
| Column 1 Cell 2   | Column 2 Cell 2    |
+-------------------+--------------------+

results in

Column 1 Heading Column 2 Heading
Column 1 Cell 1 Column 2 Cell1
Column 1 Cell 2 Column 2 Cell 2

Code

See http://docutils.sourceforge.net/docs/ref/rst/directives.html#code. Be sure to indent the code with spaces.

Example:

.. code:: php

  namespace \OxidEsales\Eshop\Community;

  class Example {}

results in

namespace \OxidEsales\Eshop\Community;

class Example {}

Highlight Text

Inline markup for menu navigation

:menuselection:`Artikel verwalten -->  Artikel`

results in: Artikel verwalten ‣ Artikel

Inline markup for file names

:file:`/usr/lib/python2.{x}/site-packages`

results in: /usr/lib/python2.x/site-packages

Inline markup for controls

:guilabel:`Cancel`

results in: Cancel

Inline markup for code

``exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']``

results in: exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

Inline markup for commands

:command:`cd ..\\GitHub\\Dokumentation-und-Hilfe`

results in: cd ..\GitHub\Dokumentation-und-Hilfe

Inline markup for downloads

:download:`/downloads/varnish/6.0.0/default.vcl`

Images

  • Do not commit big files or images. Use a link to an external source inside repository. This will help to keep repository small.

.. raw:: html

   <p>
      <img width="100" src="https://www.google.co.uk/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png"/>
   </p>

UML diagrams

Please do not commit big files or images.

Use UML source written with Plant UML or a similar tool instead of an UML image.

Note

PHPStorm has Plant UML plugin which generates UML on the fly. Look for “PlantUML tab” at the right upper corner near “Remote Host” to see generated result.

Example:

- Rendered result:

@startuml
:functions.php oxNew('oxArticle');
:oxUtilsObject::oxNew('oxArticle');
if (Find real class name in cache) then
   ->found;
   :Get class name from static cache;
else
   ->not found;
   :oxUtilsObject::getClassName();
   :oxEditionCodeHandler::getClassName();
   if (shop edition check) then
      ->Enterprise;
      :OxidEsales\Enterprise\ClassMap;
   else
      ->Professional;
      :OxidEsales\Professional\ClassMap;
   endif
   :oxModuleChainsGenerator::createClassChain('\Enterprise\Article', 'oxArticle');
   :$extensionsList = oxModuleVariablesLocator::getModuleVariable('aModules');
   :oxModuleChainsGenerator:filterInactiveExtensions($extensionsList);
   :$classExtensionsList = $extensionsList['oxArticle'];
   :oxModuleChainsGenerator:createClassExtensions($classExtensionsList, '\Enterprise\Article');

endif
:Create class with new \Enterprise\Article;
@enduml

- Code:

.. uml::

   @startuml
   :functions.php oxNew('oxArticle');
   :oxUtilsObject::oxNew('oxArticle');
   if (Find real class name in cache) then
      ->found;
      :Get class name from static cache;
   else
      ->not found;
      :oxUtilsObject::getClassName();
      :oxEditionCodeHandler::getClassName();
      if (shop edition check) then
         ->Enterprise;
         :OxidEsales\Enterprise\ClassMap;
      else
         ->Professional;
         :OxidEsales\Professional\ClassMap;
      endif
      :oxModuleChainsGenerator::createClassChain('\Enterprise\Article', 'oxArticle');
      :$extensionsList = oxModuleVariablesLocator::getModuleVariable('aModules');
      :oxModuleChainsGenerator:filterInactiveExtensions($extensionsList);
      :$classExtensionsList = $extensionsList['oxArticle'];
      :oxModuleChainsGenerator:createClassExtensions($classExtensionsList, '\Enterprise\Article');

   endif
   :Create class with new \Enterprise\Article;
   @enduml