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
-----------

External links

To be done…

Use Ref or Doc for links

Use Ref or Doc to create a link to the page of current developer documentation project.

Using Doc

Use Doc when need to link to another file in same catalog.

Example:

• Code:

  :doc:`Modules <modules/index>`
  

• Rendered result:

  Modules

Using Ref

Use Ref when need to link to specific file part. References in Sphinx are global, so use unique section name per document and time to form reference. Ref anchor schema: section_name_with_underscores-YYYYMMDD

Good examples:

• Code for Anchor inside page:

  .. _conventions_for_using_ref-20160419:
  
  Using Ref
  ---------
  

• Code for link which can be in same or other page:

  :ref:`Using Ref <conventions_for_using_ref-20160419>`
  

• Rendered link result

  Using Ref

Bad examples:

Prefixed with directory name:

.. _common_agreements-general-conventions_for_development_wiki_rst_document-20160120:

Not suffixed with date:

.. _conventions_for_development_wiki_rst_document:

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:

- 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