Escribir documentación

Alentamos a todos los usuarios de VyOS a que nos ayuden a mejorar nuestra documentación, ya que tenemos un déficit como la mayoría de los proyectos de software. Esto no solo te ayuda a ti cuando lees, sino también a todos los demás.

Si está dispuesto a contribuir con nuestra documentación, esta es la guía definitiva sobre cómo hacerlo.

Nota

A diferencia de enviar parches de código, no es necesario que abra una tarea Phabricator antes de enviar una solicitud de extracción a la documentación.

VyOS documentation is written in reStructuredText and generated to Read the Docs pages with Sphinx, as per the Python tradition. We welcome all sorts of contributions to the documentation. Not just new additions but also corrections to existing documentation.

La fuente de documentación se mantiene en el repositorio de Git en https://github.com/vyos/vyos-documentation y puede seguir las instrucciones en README.md para compilar y probar sus cambios.

You can either install Sphinx and build the documentation locally, or use the Dockerfile to build it in a container.

Pautas

Hay algunas cosas a tener en cuenta al contribuir con la documentación, en aras de la coherencia y la legibilidad.

El siguiente es un breve resumen de las reglas:

Usa inglés americano en todo momento. Siempre es una buena idea pasar el texto por un corrector gramatical y ortográfico, como Grammarly.
No olvide actualizar index.rst al agregar un nuevo nodo.
Trate de no exceder los 80 caracteres por línea, pero no rompa las URL por esto.
Cita correctamente comandos, nombres de archivos y breves fragmentos de código con doble tilde.
Use bloques literales para fragmentos más largos.
Deje una nueva línea antes y después de un encabezado.
Sangría con dos espacios.
En caso de duda, siga el estilo de la documentación existente.

Y por último, recuerda que los archivos reStructuredText no son exclusivamente para generar HTML y PDF. Deben ser legibles por humanos y fáciles de leer desde una consola.

Contenido de página

Todos los archivos RST deben seguir la misma sintaxis de nivel de TOC y deben comenzar con

#####
Title
#####

La carpeta del modo de configuración y los artículos cubren el nivel específico de los comandos. El nivel exacto depende del comando. Esto debería proporcionar estabilidad a las URL utilizadas en el foro o publicación de blog.

Por ejemplo:

establecer zona de firewall está escrito en firewall/zone.rst

establecer interfaces ethernet está escrito en interfaces/ethernet.rst

En la parte de configuración de la página, se deben documentar todas las opciones de configuración posibles. Utilice .. cfgcmd:: descrito anteriormente.

El comando de operación relacionado debe documentarse en la siguiente parte del artículo. Utilice ::opcmd.. para estos comandos.

Each page must contain the following parts:

1. Theoretical information

Theoretical information required for users to understand the next document sections:

a simple explanation of what is this page about, why or when it is required to be used

references to standards, RFCs

2. Configuration description

Describe CLI items related to the service or use case. Each config line or section must be explained, using information provided in the 1st part of the page.

3. Configuration examples

Practical examples of the service or use case configuration. They must contain topology maps (if applicable) and short descriptions.

4. Known issues

This section must contain a list of:

known issues or potential problems for the service or use case

workarounds for known issues (if any exist)

5. Debugging

Described procedures for debugging a service:

how to collect logs or other debugging information (like show commands output)

how to read and what to search for in logs and collected information

what are indicators of good and bad states in debugging outputs

Guía de estilo

Formatting and Sphinxmarkup

Nivel de COT

Usamos la siguiente sintaxis para Titulares.

#####
Title
#####

********
Chapters
********

Sections
========

Subsections
-----------

Subsubsections
^^^^^^^^^^^^^^

Paragraphs
""""""""""

Referencias cruzadas

Se utilizará un complemento para generar una etiqueta de referencia para cada titular. Para hacer referencia a una página o una sección en la documentación, use el comando :ref:.

Por ejemplo, desea hacer referencia al título VLAN en la página ethernet.rst. El complemento genera la etiqueta en función del título y la ruta del archivo.

:ref:`configuración/interfaces/ethernet:vlan

para usar un hipervínculo alternativo, úselo de esta manera:

``Revisar VLAN<configuration/interfaces/ethernet:vlan> `

manejar errores de compilación

El complemento advertirá en la compilación si un título tiene un nombre duplicado en el mismo documento. Para evitar esta advertencia, debe colocar un enlace personalizado en la parte superior del título.

Section A
==========

Lorem ipsum dolor sit amet, consetetur sadipscing elitr

Example
-------

Lorem ipsum dolor sit amet, consetetur sadipscing elitr

Section B
==========

Lorem ipsum dolor sit amet, consetetur sadipscing elitr

.. _section B example:

Example
-------

Lorem ipsum dolor sit amet, consetetur sadipscing elitr

Espacio de dirección

Tenga en cuenta los siguientes RFC (RFC 5737, RFC 3849, RFC 5389 y RFC 7042), que describen las direcciones IP públicas reservadas y los números de sistema autónomo para la documentación:

192.0.2.0/24

198.51.100.0/24

203.0.113.0/24

2001:db8::/32

ASN de 16 bits: 64496 - 64511

ASN de 32 bits: 65536 - 65551

Direcciones MAC de unidifusión: 00-53-00 a 00-53-FF

Direcciones MAC de multidifusión: 90-10-00 a 90-10-FF

Por favor, no utilice otro espacio de megafonía pública.

Longitud de la línea

Limite todas las líneas a un máximo de 80 caracteres.

Excepto en .. code-block:: porque usa la etiqueta html ``<pre> `` y presenta el mismo formato de línea del primer archivo de origen.

Filtro automático

Cada solicitud de extracción de GitHub se filtra automáticamente para verificar el espacio de direcciones y la longitud de la línea.

A veces es necesario proporcionar direcciones IP reales como en los ejemplos. Para esto, utilice la sintaxis de comentarios de sphinx .. stop_vyoslinter para detener el linter y .. start_vyoslinter para comenzar.

Marcado personalizado de Sphinx-doc

Se han desarrollado comandos personalizados para escribir la documentación. Siéntase cómodo con esos comandos, ya que esto facilita la forma en que representamos la documentación.

cfgcmd

Al documentar los comandos CLI, use la directiva .. cfgcmd:: para todos los comandos del modo de configuración. Se debe agregar una explicación del comando descrito debajo de esta declaración. Reemplace todos los contenidos variables con<value> o algo similar.

Con esos comandos personalizados, será posible representarlos de una manera más descriptiva en el manual HTML/PDF resultante.

.. cfgcmd:: protocols static arp <ipaddress> hwaddr <macaddress>

   This will configure a static ARP entry, always resolving `192.0.2.100` to
   `00:53:27:de:23:aa`.

Para un comando de nivel de configuración en línea, use :cfgcmd:

:cfgcmd:`set interface ethernet eth0`

Para extraer un valor predeterminado de las definiciones XML, agregue una directiva :defaultvalue: a .. cfgcmd::. Para tener esta función localmente, el submódulo vyos-1x debe inicializarse antes. Tenga en cuenta que no debe actualizar el submódulo en su PR.

.. cfgcmd:: set system conntrack table-size <1-50000000>
    :defaultvalue:

    The connection tracking table contains one entry for each connection being
    tracked by the system.

opcmd

Al documentar los comandos de nivel operativo, utilice la directiva .. opcmd::. Se debe agregar una explicación del comando descrito debajo de esta declaración.

Con esos comandos personalizados, es posible representarlos de una manera más descriptiva en el manual HTML/PDF resultante.

.. opcmd:: show protocols static arp

   Display all known ARP table entries spanning across all interfaces

Para un comando de nivel operativo en línea, use :opcmd:

:opcmd:`add system image`

cmincluir

Para minimizar la redundancia, existe una directiva de inclusión especial. Incluye un archivo txt y reemplaza {{ var0 }} - {{ var9 }} con el valor correcto.

.. cmdinclude:: /_include/interface-address.txt
   :var0: ethernet
   :var1: eth1

el contenido de interface-address.txt se ve así

.. cfgcmd:: set interfaces {{ var0 }} <interface> address <address | dhcp |
   dhcpv6>

   Configure interface `<interface>` with one or more interface
   addresses.

   * **address** can be specified multiple times as IPv4 and/or IPv6
   address, e.g. 192.0.2.1/24 and/or 2001:db8::1/64
   * **dhcp** interface address is received by DHCP from a DHCP server
   on this segment.
   * **dhcpv6** interface address is received by DHCPv6 from a DHCPv6
   server on this segment.

   Example:

   .. code-block:: none

      set interfaces {{ var0 }} {{ var1 }} address 192.0.2.1/24
      set interfaces {{ var0 }} {{ var1 }} address 192.0.2.2/24
      set interfaces {{ var0 }} {{ var1 }} address 2001:db8::ffff/64
      set interfaces {{ var0 }} {{ var1 }} address 2001:db8:100::ffff/64

vytarea

Cuando se hace referencia a las tareas de VyOS Phabricator, hay un comando de Sphinx Markup personalizado llamado vytask que se convierte automáticamente en una URL de Phabricator adecuada. Esto se usa mucho en la sección Changelog.

* :vytask:`T1605` Fixed regression in L2TP/IPsec server
* :vytask:`T1613` Netflow/sFlow captures IPv6 traffic correctly

Flujo de trabajo de bifurcación

El flujo de trabajo de bifurcación es fundamentalmente diferente de otros flujos de trabajo populares de Git. En lugar de usar un único repositorio del lado del servidor para que actúe como base de código "central", le da a cada desarrollador su propio repositorio del lado del servidor. Esto significa que cada colaborador no tiene uno, sino dos repositorios Git: uno local privado y uno público del lado del servidor.

La principal ventaja del flujo de trabajo de bifurcación es que las contribuciones se pueden integrar sin la necesidad de que todos presionen a un solo repositorio central. Los desarrolladores ingresan a sus propios repositorios del lado del servidor, y solo el mantenedor del proyecto puede ingresar al repositorio oficial. Esto permite que el mantenedor acepte compromisos de cualquier desarrollador sin darles acceso de escritura a la base de código oficial.

Nota

Las actualizaciones de nuestra documentación deben enviarse mediante una solicitud de extracción de GitHub. Esto requiere que ya tengas una cuenta de GitHub.

Fork este proyecto en GitHub https://github.com/vyos/vyos-documentation/fork
Clone fork a la máquina local, luego cambie a ese directorio $ cd vyos-documentation
Instale los requisitos $ pip install -r requirements.txt (o algo similar)
Crea una nueva rama para tu trabajo, usa un nombre descriptivo de tu trabajo: ``$ git checkout -b<branch-name> ``
Realice todos sus cambios; tenga en cuenta nuestras reglas de confirmación (Preparar parche/confirmar). Esto se aplica principalmente a los mensajes de confirmación adecuados que describen su cambio (cómo y por qué). Consulte la documentación de Sphinx-doc o reStructuredText si no está familiarizado con él. Esto se utiliza para escribir nuestros documentos. Se pueden obtener directivas adicionales sobre cómo escribir en RST en reStructuredTextDirectives.
Verifique sus cambios creando localmente la documentación $ make livehtml. Sphinx construirá los archivos html en la carpeta docs/_build. Le proporcionamos un contenedor Docker para una experiencia de usuario fácil de usar. Consulta el archivo README.md de este repositorio.
Vea los archivos modificados llamando a $ git status. Obtendrá una descripción general de todos los archivos modificados por usted. Puede agregar archivos individuales al Índice de Git en el siguiente paso.
Agregue archivos modificados al índice de Git $ git add path/to/filename o agregue todos los archivos no preparados $ git add .. Todos los archivos agregados al índice de Git serán parte de usted después de la confirmación de Git.
Confirma tus cambios con el mensaje $ git commit -m "<commit message> " o use $ git commit -v para iniciar su editor configurado. Puede escribir un mensaje de confirmación. Nuevamente, siéntase cómodo sin reglas (Preparar parche/confirmar).
Envía confirmaciones a tu proyecto de GitHub: ``$ git push -u origin<branch-name> ``
Enviar solicitud de extracción. En GitHub, visite el repositorio principal y debería ver un banner que sugiere realizar una solicitud de extracción. Rellena el formulario y describe lo que haces.
Una vez que se hayan aprobado las solicitudes de extracción, es posible que también desee actualizar localmente su repositorio bifurcado. Primero tendrás que agregar un segundo control remoto llamado upstream que apunta a nuestro repositorio principal. $ git remote add upstream https://github.com/vyos/vyos-documentation.git

Verifique sus repositorios remotos configurados:
```
$ git remote -v
origin    https://github.com/<username>/vyos-documentation.git (fetch)
origin    https://github.com/<username>/vyos.documentation.git (push)
upstream  https://github.com/vyos/vyos-documentation.git (fetch)
upstream  https://github.com/vyos/vyos-documentation.git (push)
```
Tu repositorio remoto en Github se llama origin, mientras que el repositorio original que has bifurcado se llama upstream. Ahora puede actualizar localmente su repositorio bifurcado.
```
$ git fetch upstream
$ git checkout current
$ git merge upstream/current
```
If you also want to update your fork on GitHub, use the following: $ git push origin current