Guías de documentación

Propósito

La documentación principal de Tryton está escrita usandoreStructuredTexty se convierte a una variedad de formatos diferentes usandoSphinx.

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

Algunos de los puntos más importantes también se mencionan aquí junto con cualquier área que sea diferente o específica de Tryton.

Siempre que sea apropiado, debe intentar seguir las reglas proporcionadas en este documento. Si algo no se menciona aquí, pero la guía de estilo de Python lo menciona, intente seguirlo. Si ninguno de los dos tiene una opinión al respecto, pero ya está hecho de una manera particular en la documentación existente, intente seguirlo. El verdadero objetivo es tener una estructura y un estilo consistentes para toda la documentación.

Estilo general

Uso de espacios en blanco

Los puntos clave a tener en cuenta son:

Usarsemantic line breaks.
Usa una indentación estándar de 3 espacios, sin tabulaciones.
El contenido de la lista debe tener sangría para que se alinee con el inicio del texto en la primera línea.
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

La longitud máxima de línea para texto normal es 79 caracteres. Esto puede excederse para tablas y enlaces largos que no forman parte de un párrafo.

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 altrytoncomando para el cliente de escritorio.

También evita usar la palabra ERP después de Tryton. Esto se debe a que Tryton puede usarse para más que planificación de recursos empresariales.

Secciones

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

#con línea superpuesta, para el título del proyecto o módulo en elindex.rstarchivo
*con línea superpuesta, para los títulos principales en los otros principales.rstarchivos o subdirectorioindex.rstarchivos
=, para secciones
-, para subsecciones
^, para subsubsecciones
", para párrafos

Anclas

Para facilitar la vinculación de la documentación y la búsqueda de objetos Tryton en función de sus__name__usa anclas definidas explícitamente.

Para todosconceptos, modelos, asistentes, informesyconfigLas configuraciones colocan un ancla antes de su título usando el tipo de objeto seguido de un guión (-), luego el objeto completo__name__.

Entonces, por ejemplo, para el modelo de compra y el informe usaría:
```
.. _model-purchase.purchase:

Purchase Model
==============

.. _report-purchase.purchase:

Purchase Report
---------------
```
Cada paso de configuración y uso también debe tener un ancla definida. Para estos, el ancla debe coincidir con el título, de modo que se pueda vincularlos sin necesidad de duplicar el título en el enlace de referencia.

Enlaces

Es bueno proporcionar al lector enlaces a cualquier concepto o instrucción que se describa en otra parte y que sea relevante para el elemento que se está documentando.

The default_role is set to ref. Esto permite crear enlaces sin necesidad de anteponerles:ref:.
Agrega un enlace cada vez que un elemento se mencione por primera vez dentro de una sección. Esto se debe a que el lector puede haber llegado directamente a esa sección y no haber visto enlaces en partes anteriores del documento.
Cuando un elemento se menciona más de una vez, se pueden diseñar menciones adicionales utilizando el*Item*formato. Esto también debería usarse en lugar de crear un enlace al mencionar la sección actual.
Los enlaces deben crearse con un título explícito, por ejemplo`Link Title <target>`.
La documentación usaintersphinxpara permitir enlaces a la documentación de otros módulos. Al vincular a destinos en otros módulos, siempre anteponga al destino el nombre del módulo seguido de dos puntos (:) por ejemplo`Link Title <module:target>`.
También puede crear un enlace a otro módulo vinculándolo al enlace de ese módulo.index.rst file. For example:
```
Services can be defined in the :doc:`Product Module <product:index>`.
```

Marcado en línea

Donde esté disponiblestandard reStructuredText markupyRoles de Sphinxse puede utilizar (excepto en elindex.rst file).

Los valores literales siempre deben estar entre comillas dobles (``) para evitar que el valor sea interpretado como una referencia por el rol predeterminado.

Algunos ejemplos útiles de roles estándar incluyen:

:abbr:`TST (Test Sphinx Thing)`

Se utiliza para definir abreviaturas. La definición de la abreviatura se puede dar entre paréntesis y solo se muestra como información sobre herramientas.

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

Usado para nombres de archivo. Las partes que pueden variar se pueden incluir con{variable}sintaxis, estos se muestran de manera diferente para indicar que deben reemplazarse por el valor correcto cuando se usan.

:guilabel:`Open related records`

Se utiliza para cualquier elemento delGUI. Esto incluye etiquetas de botones, títulos de ventanas, nombres de menús, etc.

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

Usado para elementos de menú. Cada nivel se separa usando-->.

Para crear un:menuselection:elemento que también es un enlace que necesita para utilizar sustituciones:

This is found in the main menu:

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

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

warningCuando sea posible, intenta poner:menuselection:elementos en un párrafo con sangría propia para que no se crucen entre líneas. Si esto no es posible, enciérrelos en[corchetes]para ayudar a que sean más fáciles de leer.

:rfc:`2324`

Usado para enlaces a Internet Request for Comments. Usa solo el número de RFC.

Estructura

Módulos

La documentación de un módulo debe colocarse dentro deldocdirectorio que se encuentra en el módulo. Dependiendo de lo que haga el módulo y de cómo esté estructurado, es posible que necesite algunos o todos los siguientes archivos:

conf.py

Este archivo es obligatorio y es el archivo de configuración de Sphinx. Debe mantenerse exactamente igual que elconf.pyarchivos en todos los demás módulos.

index.rst

Este archivo también es obligatorio y debe incluir una descripción básica del módulo y una tabla de contenidos (toctreedirectiva) que enlaza con los otros archivos con unmaxdepth of 2.

warningEn este archivo use solo marcado de texto reestructurado estándar, no use ningún rol o directiva específica de Sphinx, exceptotoctree. Esto se debe a que este archivo se usa como elREADME.rst, y también como el de la distribuciónlong_description. Su contenido se muestra enPyPI, y PyPI no soporta directivas ni roles de Sphinx. Usarlos causará problemas al empaquetar el módulo para su distribución.

La razón por la que está bien usar untoctreeLa directiva se debe a que el proceso de compilación los conoce y los elimina automáticamente al compilar el archivo de distribución.

setup.rst

El objetivo de este archivo es describir cualquier configuración que deba realizarse una vez que se haya activado un módulo. A menudo, el usuario deberá realizar esta configuración antes de que el módulo pueda utilizarse correctamente.

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

El contenido de este archivo está destinado a los usuarios del sistema. Por lo tanto, debería hablar directamente con estos lectores y usted puede referirse a ellos en segunda persona. Esto significa que puedes usar oraciones como"Tu sistema ... entonces necesitas ...".

Debe contener secciones que proporcionen instrucciones u orientación sobre el uso de una función del módulo, por ejemplo"Uso de la funcionalidad principal del módulo", o"Trabajo con una parte específica del módulo".

configuration.rst

Este archivo debe contener cada una de las opciones de configuración del servidor que proporciona el módulo. Cada opción de configuración debe describirse mencionando para qué sirve o para qué sirve.

design.rst

El diseño y estructura del módulo se describe en este archivo. Intente centrarse en los conceptos que el módulo introduce o amplía. A menudo, estos conceptos se implementan en Tryton como modelos, pero lo importante son los conceptos y cómo encajan entre sí.

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

Los asistentes y los informes deben documentarse en secciones debajo de los conceptos con los que se relacionan. Si se utilizan con varios modelos diferentes, documentelos como parte del modelo principal o del primero con el que se relacionan y luego vincúlelos desde cualquier otro modelo que los utilice.

reference.rst

Este archivo se utiliza para proporcionar información de referencia para las personas que están desarrollando o trabajando en el módulo. Incluye secciones que documentan las API o rutas que proporciona el módulo, así como documentación sobre cómo crear o actualizar partes del módulo.

releases.rst

Este archivo se usa para incluir elCHANGELOG.

En algunos casos, un módulo grande puede requerir mucha documentación. Puede tener sentido dividir estos archivos en partes más pequeñas. Para hacer esto, el archivo debe reemplazarse con un directorio con el mismo nombre, pero sin el.rstextensión. Los archivos separados deben agregarse a este directorio con la extensión.inc.rst, y debería haber unindex.rstexpediente con la directivaincludepara cada archivo separado.