Documentation Guidelines

Purpose

The main Tryton documentation is written using reStructuredText and is converted into a variety of different formats using Sphinx.

For most things this style guide aims to be consistent with the Python style guide.

Some of the most important points are also mentioned here along with any areas that are different, or are specific to Tryton.

Wherever appropriate you should try follow the rules given in this document. If something is not mentioned here, but the Python style guide mentions it, then try and follow that. If neither have an opinion on it, but it is already done a particular way in the existing documentation then try and follow that. The real aim is to have a consistent structure and style for all the documentation.

General Style

Use of Whitespace

The key things to take note of are:

• Start each sentence on a new line. This results in simpler code reviews and diffs when changes need to be made in the future.
• Use a standard indentation of 3 spaces, with no tabs.
• List's contents should be indented so that it lines up with the start of the text in the first line.
• Blocks of code should be indented the way they would normally be indented.

For example:

A sentence should end with a full stop. There should be a single space
before the start of the next sentence.

Indentation
   The blank space between the start of a line and where the text
   starts.

   .. note::

      This is where the text should normally be indented to.

* This is a list item
  with two lines of text.

  * And a sub list

#. This is a numbered list item
   with multiple lines of
   text.

Line Length

The maximum line length for normal text is 79 characters. This can be exceeded for tables and long links that are not part of a paragraph.

Capitalisation

Try and follow the rules in the Python style guide, so:

• Use sentence case for section titles.
• Except for the names of objects. In section titles these should use title case.

To ensure consistency for certain words and terms always use:

Tryton

This is always capitalised, unless referring to the tryton command for the desktop client.

Also avoid using the word ERP after Tryton. This is because Tryton can be used for more than just enterprise resource planning.

Sections

Section heading styles follow the Python style guide:

• # with overline, for the project or module title in the index.rst file
• * with overline, for the main titles in the other main .rst files or subdirectory index.rst files
• =, for sections
• -, for subsections
• ^, for subsubsections
• ", for paragraphs

Anchors

In order to make it easy to link the documentation together, and find Tryton objects based on their __name__ use explicitly defined anchors.

• For all concepts, models, wizards, reports and config settings place an anchor before their title using the object's type followed by a dash (-), then the object's full __name__.

  So, for example, for the purchase model and report you would use:

  .. _model-purchase.purchase:
  
  Purchase Model
  ==============
  
  .. _report-purchase.purchase:
  
  Purchase Report
  ---------------

• Each setup and usage step should also have an anchor defined. For these the anchor should match the title, so that they can be linked to without needing to duplicate the title in the reference link.

Links

It's good to provide the reader with links to any concepts or instructions that are described elsewhere and relevant to the item being documented.

• The default_role is set to ref. This allows links to be created without needing to prefix them with :ref:.
• Add a link each time an item is first mentioned within a section. This is because the reader may have just jumped into the document at the current section and not seen any links in earlier parts of the document.
• When an item is mentioned more than once extra mentions can be styled using the *Item* format. This should also be used instead of creating a link when mentioning the current section.
• Links should be created with an explicit title, for example `Link Title <target>`.
• The documentation uses intersphinx to allow links to other module's documentation. When linking to targets in other modules always prefix the target with the module name followed by a colon (:) for example `Link Title <module:target>`.
• You can also create a link to another module by linking to that module's index.rst file. For example:

  Services can be defined in the :doc:`Product Module <product:index>`.

Inline Markup

Where available standard reStructuredText markup and Sphinx roles can be used (except in the index.rst file).

Literal values should always be surrounded by double backticks (``) to avoid the value being interpreted as a reference by the default role.

A few useful examples of standard roles include:

:abbr:`TST (Test Sphinx Thing)`

Used to define abbreviations. The abbreviation definition can be given inside brackets and is only shown as a tooltip.

:command:`trytond_import_countries`

Used for the name of commands or scripts.

:doc:`Style Guide <style>`

Used to link to a documentation file.

:file:`modules/{module_name}/doc/index.rst`

Used for filenames. Parts that may vary can be included with {variable} syntax, these are displayed differently to indicate that they should be replaced by the correct value when used.

:guilabel:`Open related records`

Used for any element in the GUI. This includes button labels, window titles, menu names, and so on.

:menuselection:`Administration --> Users --> Users`

Used for menu items. Each level is separated using -->.

To create a :menuselection: item that is also a link you need to use substitutions:

This is found in the main menu:

   |Menu --> Sub Menu --> Item|__.

   .. |Menu --> Sub Menu --> Item| replace:: :menuselection:`Menu --> Sub Menu --> Item`
   __ https://example.com/

warning Where possible try and put :menuselection: items in an indented paragraph of their own so they won't break across lines. If this is not possible then enclose them in [square brackets] to help make them easier to read.

:rfc:`2324`

Used for links to Internet Request for Comments. Just use the RFC's number.

Structure

Modules

A module's documentation should be placed inside the doc directory found in the module. Depending on what the module does, and how it is structured you may need some, or all, of the following files:

conf.py

This file is required, and is the Sphinx configuration file. It must be kept exactly the same as the conf.py files in the all the other modules.

index.rst

This file is also required and should include a basic description of the module and a table of contents (toctree directive) that links to the other files with a maxdepth of 2.

warning In this file use only standard restructured text markup, do not use any Sphinx specific roles or directives, except toctree. This is because this file is used as the module's README.rst, and also as the distribution's long_description. It's contents is displayed on PyPI, and PyPI doesn't support Sphinx directives and roles. Using them will cause problems when packaging the module for distribution.

The reason it is okay to use a toctree directive is because the build process knows about these and automatically strips them out when building the distribution file.

setup.rst

The aim of this file is to describe any setup that needs to be done once a module has been activated. Often this setup will need to be done by the user before the module can be used properly.

Add sections to this file that describe the setup that is required and how it is done, for example "Doing a specific module setup task", or "Setting up the thing to do something".

usage.rst

The contents of this file are intended for users of the system. So it should talk to these readers directly and you can refer to them in the second person. This means you can use sentences like "Your system ... then you need to ...".

It should contain sections that provide instructions or guidance on using a feature of the module, for example "Using the main feature in the module", or "Working with a specific part of the module".

configuration.rst

This file should contain each of the server configuration settings that the module provides. Each configuration option should be described mentioning what it is for, or what it does.

design.rst

The design and structure of the module is described in this file. Try and focus on the concepts that the module introduces or extends. Often these concepts are implemented in Tryton as models, but it is the concepts and how they fit together that are important.

Avoid specifically mentioning models, fields, or selection values these are documented in the code with doc strings and help text.

Wizards and reports should be documented in sections beneath the concepts that they relate to. If they are used with several different models then document them as part of either the primary, or first, model that they relate to, and then link to them from any other models that use them.

reference.rst

This file is used to provide reference information for people who are developing or working on the module. It includes sections that document any APIs or routes the module provides, as well as documentation on how to build or update parts of the module.

releases.rst

This file is used to include the CHANGELOG.

In some cases a large module may require lots of documentation. It can make sense to split up these files into smaller parts. To do this the file should be replaced with a directory of the same name, but without the .rst extension. The separate files should be added to this directory with the extension .inc.rst, and there should be an index.rst file with the directive include for each separate file.