Skip to content

conventions.rst

Latest commit

 

History

History
267 lines (161 loc) · 5.02 KB

conventions.rst

File metadata and controls

267 lines (161 loc) · 5.02 KB

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:

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

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

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: :menuselection:`Artikel verwalten --> Artikel`

Inline markup for file names

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

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

Inline markup for controls

:guilabel:`Cancel`

results in: :guilabel:`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: :command:`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 .svg images and include them like described in the section :ref:`Images <conventions_images>`. If you created the UML diagram with PlantUml, its good to also add the .puml file to the repository into a separate directory :file:`resources`.