Guías de documentación

Propósito

La documentación principal de Tryton está escrita usando reStructuredText and is converted into a variety of different formats using Sphinx.

Para la mayoría de los casos, esta guía de estilo busca ser coherente con Guía de estilo de Python.

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.

Estilo general

Uso de espacios en blanco

Los puntos clave a tener en cuenta son:

Usar semantic line breaks.
Usa una indentación estándar de 3 espacios, sin tabulaciones.
List's contents should be indented so that it lines up with the start of the text in the first line.
Los bloques de código deben indentarse como se indentarían normalmente.

Por ejemplo:

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.

Longitud de línea

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.

Uso de mayúsculas

Intenta seguir las reglas de la guía de estilo de Python, de modo que:

Usa estilo oración para los títulos de sección.
Excepto los nombres de objetos. En títulos de sección deben usar mayúsculas de título.

Para asegurar consistencia en ciertas palabras y términos, usa siempre:

Tryton: Esto siempre se escribe con mayúscula, excepto cuando se refiere al tryton comando para el cliente de escritorio.

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

Secciones

Los estilos de encabezado de sección siguen la guía de estilo de Python:

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

Anclas

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

Para todos conceptos, modelos, asistentes, informes y 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.

Enlaces

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.
Los enlaces deben crearse con un título explícito, por ejemplo `Link Title <target>`.
La documentación usa 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>`.
```

Marcado en línea

Donde esté disponible standard reStructuredText markup y Roles de Sphinx 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.

Algunos ejemplos útiles de roles estándar incluyen:

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

Usado para el nombre de comandos o scripts.

:doc:`Style Guide <style>`

Usado para enlazar a un archivo de documentación.

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

Para crear un :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/

advertencia Cuando sea posible, intenta poner :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.

Estructura

Módulos

La documentación de un módulo debe colocarse dentro del 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.

advertencia 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, y también como el de la distribución 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.

Agrega secciones a este archivo que describan la configuración requerida y cómo se realiza, por ejemplo "Realizar una tarea específica de configuración del módulo", o "Configurar el elemento para hacer algo".

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 "Tu sistema ... entonces necesitas ...".

It should contain sections that provide instructions or guidance on using a feature of the module, for example "Uso de la funcionalidad principal del módulo", o "Trabajo con una parte específica del módulo".

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.

Evita mencionar específicamente modelos, campos o valores de selección; estos se documentan en el código con docstrings y texto de ayuda.

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

Este archivo se usa para incluir el 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, y debería haber un index.rst file with the directive include for each separate file.