Contribuir a la Documentación
La documentación es una forma de describir un proceso simple o complejo para un usuario final, dado que en el día a día existen muchas actividades y muy poco tiempo siempre es bueno contar con una guía para realizar los procesos que a veces se olvidan.
Este material elaborado por E.R.P. Consultores y Asociados, C.A. está dirigido a las personas que se encargan de documentar cualquier proceso, paso a paso, guía de usuario o simplemente una publicación bajo el uso de la herramienta “reStructuredText”. Tome en cuenta todas las consideraciones expresadas en esta guía para evitar problemas de escalabilidad a futuro y mantenimiento.
A diferencia de “Markdown”, la documentación en “rST” no es realizada de forma local, por lo tanto el equipo de trabajo necesita conexión a internet para visualizar los cambios realizados en la documentación.
Las colaboraciones a dicha documentación son realizadas por medio de “GitHub”. El repositorio del usuario debe ser actualizado para extraer del repositorio “erpcya/docs” los cambios. Para contribuir a la documentación de ERPyA, el usuario debe cumplir con tres (3) requerimientos necesarios indicados a continuación y acceder a https://github.com/erpcya/docs/issues para contribuir:
Tener el repositorio de ERPyA clonado en su versión actualizada.
Tener usuario en Read the Docs
Tener creado un proyecto con la url del repositorio de ERPyA
En el caso de que el usuario no cumpla con los requerimientos establecidos y desconozca la manera de obtenerlos, puede ingresar al documento Crear un Proyecto en Read the Docs, y seguir el procedimiento indicado para cumplir con los requerimientos necesarios.
Cuando el usuario cumpla con los requerimientos indicados anteriormente y desee realizar contribuciones a las documentaciones, el mismo debe iniciar sesión en “Read the Docs”, abrir el editor de texto instalado previamente (Puede ser utilizado Visual Studio Code) y realizar lo siguiente:
Seleccione en la barra de herramientas de “Visual Studio Code”, la opción “Terminal”, luego seleccione la opción “Nueva Terminal”. Ejecute el siguiente comando en la terminal: git remote add upstream https://github.com/erpcya/docs.git
Luego de haber configurado “Visual Studio Code”, puede proceder a realizar o actualizar la documentación.
Apuntes para la Documentación
El lenguaje “reStructuredText” o “rST” es muy parecido al lenguaje “Markdown”, al momento de documentar en “rST” se deben tener en cuenta algunos detalles diferentes de “Markdown”:
Identificación del Documento
Al principio del documento es recomendable identificarlo con una etiqueta, la misma se compone de dos puntos continuos “..”, seguido de un espacio en blanco y por último el símbolo “_”, pegado de la palabra “documento”, con el símbolo “/” y el nombre del documento, finalizando con el símbolo “:”
Ejemplo:
.. _documento/contribuir:
La etiqueta al principio del documento es una forma de clasificación ordenada que sirve de utilidad al usuario para llamarlo cuando sea necesario en cualquier otro documento. El llamado de un documento se puede realizar por medio de la siguiente etiqueta:
:ref:`documento/contribuir`
Ejemplo:
Si desea contribuir a esta documentación, puede tomar como guia el documento realizado por E.R.P. Consultores y Asociados con la finalidad de que los usuario puedan :ref:`documento/contribuir`.
Titulos
Los titulos en “rST” son identificados por caracteres especiales
# Con revestimiento, para piezas
* Con overline, para capítulos
=, Para secciones
-, Para subsecciones
^, Para las subsecciones
", Para párrafos
Los mismos, pueden ser utilizados de la siguiente manera en un documento
=============================
Contribuir a la Documentación
=============================
Apuntes para la Documentación
=============================
Identificación del Documento
****************************
Tabla Compleja
--------------
Formato para Listas Numericas
La numeración en la documentación se realiza agregando:
* Punto uno
- Punto dos
+ Punto tres
Punto cuatro
1. Punto cinco
La misma es visualizada de la siguiente manera:
Punto uno
Punto dos
Punto tres
Punto cuatro
Punto cinco
Formato de Párrafos
Los párrafos son simplemente fragmentos de texto separados por una o más líneas en blanco. En “reStructuredText” se puede dar formato a los párrafos de la siguiente manera:
- Un asterisco: *text* para énfasis (cursiva),
- Dos asteriscos: **text** para un fuerte énfasis (negrita) y
- Comillas inversas: ``text`` para muestras de código.
Ejemplo:
Un asterisco: text para énfasis (cursiva),
Dos asteriscos: text para un fuerte énfasis (negrita) y
Comillas inversas:
textpara muestras de código.
Tenga en cuenta algunas restricciones de este marcado:
No puede estar anidado
El contenido puede no comenzar o terminar con espacios en blanco entre los asteriscos: * text*
Formato para Tablas
En rST se pueden realizar dos tipos de tablas:
Tabla Compleja
Permite adaptar las celdas al requerimiento que tenga el usuario para plasmar la información.
+------------------------+--------------------------+------------------------------+-----------------+
| Requerimientos | Usuario | Contraseña | Documentación |
| del Usuario | | del Usuario | Publica |
+========================+==========================+==============================+=================+
| GitHub | UsuarioEstandar | Clave Secreta |Perfil en GitHub |
+------------------------+--------------------------+------------------------------+-----------------+
| Read the Docs | uEstandar | uEstandar |Proyectos Creados|
+------------------------+--------------------------+------------------------------+-----------------+
Ejemplo de Tabla Compleja:
- Requerimientos
del Usuario
Usuario
Contraseña del Usuario
- Documentación
Publica
GitHub
UsuarioEstandar
Clave Secreta
Perfil en GitHub
Read the Docs
uEstandar
uEstandar
Proyectos Creados
Tabla Sencilla
Permite al usuario plasmar la información en una tabla sencilla.
============== =============== =============
Requerimientos Usuario Contraseña
============== =============== =============
Read the Docs uEstandar uEstandar
GitHub UsuarioEstandar Clave Secreta
============== =============== =============
Ejemplo de Tabla Sencilla:
Requerimientos
Usuario
Contraseña
Read the Docs
uEstandar
uEstandar
GitHub
UsuarioEstandar
Clave Secreta
Formato para Imágenes
Las imágenes pueden ser llamadas en la documentación de dos (2) formas:
Llamado de Imagen
"Ejemplo de una imagen":
.. documento/contribuir-01
.. figure:: resources/img1.png
:alt: Inicio de Sesión en GitHub
Imagen 1. Inicio de Sesión en GitHub
"Ejemplo de otra imagen":
.. documento/contribuir-02
.. figure:: resources/img2.png
:alt: Perfil de ERPyA en GitHub
Imagen 2. Perfil de ERPyA en GitHub
Note
.. documento/contribuir-01: Etiqueta de referencia para ordenar las imágenes en el código por si ocurre un error con las mismas... figure:: img/img1.png: Etique para llamar las imágenes.:alt:: Etiqueta para el nombre de la imagen por si falla la visualización de la misma. Esta debe colocarse dejando tres (3) espacios en blanco despues de donde comienza la identación de la etiqueta.. figure:: img/img1.png.Imagen 1. Inicio de Sesión en GitHub: Referencia para mostrar por orden las imágenes en el documento y agregar su título o descripción.
Llamado de Imagen por Etiqueta
“Ejemplo de ruta de la imagen”:
.. |Inicio de Sesión en GitHub| image:: img/img1.png
.. |Perfil de ERPyA en GitHub| image:: img/img2.png
Note
.. |Inicio de Sesión en GitHub| image:: img/img1.png: Etiqueta de ruta de la imagen. Esta etiqueta debe agregarse al principio del documento y antes de la etiqueta de identificación del documento.
"Ejemplo de llamado de una imagen en el documento":
Ingrese a su usuario de "GitHub" en https://github.com/.
|Inicio de Sesión en GitHub|
Imagen 1. Inicio de Sesión en GitHub
"Ejemplo de llamado de otra imagen en el documento":
Luego ubique el perfil de `ERPyA`_ ubicado en https://github.com/erpcya, para buscar el repositorio de la documentación "docs". La búsqueda del repositorio puede ser realizada de forma manual o buscando la palabra "docs" en la barra de búsqueda inteligente.
|Perfil de ERPyA|
Imagen 2. Perfil de ERPyA
Note
|Perfil de ERPyA|: Llamado de la imagen en el documento. Esta puede ser llamada cuando se necesite a lo largo del documento.Imagen 2. Perfil de ERPyA: Referencia para mostrar por orden las imágenes en el documento y agregar su título o descripción.
Formato para Notas y Alertas
Para agregar correctamente una nota o alerta, es necesario tomar en cuenta lo siguiente:
No dejar espacios en blanco al comenzar la línea donde sera definida la etiqueta de la nota o alerta.
Definir la etiqueta de la nota
.. note::, o alerta.. warning::Dejar una línea libre entre la etiqueta de la nota
.. note::, o alerta.. warning::y el contenido de la misma.Dejar una sangría de cuatro (4) espacios en blanco, en la línea del contenido.
Reglas para Crear una Documentación
E.R.P. Consultores y Asociados, C.A. tiene establecido como estándar de nombre de archivos, directorio e imágenes de la documentación en “reStructuredText” lo siguiente.
Nombre del Archivo de la Documentación
El nombre del archivo debe respetar lo siguiente:
Debe ser un nombre que describa la funcionalidad.
El nombre debe ser en inglés.
Los espacios en blanco se deben sustituir por guiones (-).
No debe poseer caracteres especiales: !@#$%*()_=+/?<>~
La extensión del archivo debe ser rst
El nombre debe ser todo en minúscula.
Ejemplo de un nombre de archivo: setup-vmax-220.rst
Directorio de la Documentación
Dependiendo de lo complejo de la documentación se define la estructura de directorios, sea lo mas específico posible y preguntese primero lo siguiente:
¿La documentación tiene muchas secciones?
¿Las funcionalidades son completamente separadas?
¿Tiene relación un documento con otro?
Con base en las preguntas deberá determinar si debe agregar un directorio nuevo al directorio principal o simplemente usar uno que ya exista.
Un ejemplo es la localización realizada por E.R.P. Consultores y Asociados, C.A. para Venezuela, a continuación se presenta:
¿La documentación tiene muchas secciones? Si puede tener varias secciones como:
Impresión fiscal
Retenciones
Tesorería
Reportes fiscales
¿Las funcionalidades son completamente separadas? Pertenecen a un sub-grupo llamado localización Venezuela que practicamente no forma parte del core de ADempiere
¿Tiene relación un documento con otro? Si, entre cada una de las funcionalidades de la localización se tiene mucha relación.
Todo esto indica que se debe crear un directorio dentro del directorio principal y dentro de ese directorio deberá existir un directorio por funcionalidad,
Ejemplo de Directorio Principal: docs
Árbol de directorios:
docs/
lve/
fiscal-printer/
setup-vmax-220.rst
withholding/
finance/
fiscal-reports/
Note
Para el nombre de los directorios se debe respetar la misma definición utilizada para los nombres de los archivos.
Directorio de las Imágenes de la Documentación
El directorio de las imágenes se debe crear dentro del directorio de la funcionalidad, un ejemplo de ello puede ser el siguiente:
Siguiendo con el ejemplo anterior, si se desea agregar alguna imagen al documento “setup-vmax-220.rst” se debe crear un directorio llamado “resources” dentro del directorio “fiscal-printer”, el resultado quedaría como el siguiente:
Ejemplo de Directorio de las Imágenes:
Árbol de directorios:
docs/
lve/
fiscal-printer/
resources/
setup-vmax-220.rst
withholding/
finance/
fiscal-reports/
Note
Para el nombre de las imágenes se debe respetar la misma definición utilizada para los nombres de los archivos.
Comandos para Documentación
Descargar Repositorio
Para descargar el repositorio en la carpeta local y poder contribuir a la documentación, es necesario ejecutar los siguientes comandos en la terminal de “Visual Studio Code”.
Comando para ubicarse en la carpeta donde se va a almacenar el repositorio cd /opt/Development/Workspace/
Copie la url del repositorio de ERPyA con la opción “Clone or download”
Imagen 1. Opción Clonar o Descargar Repositorio
Comando para descargar el repositorio clonado en la carpeta local seleccionada git clone https://github.com/erpcya/docs.git
Note
La url introducida en el comando es la copiada desde la opción “Clone or download” del repositorio de ERPyA.
Actualizar Repositorio
Para contribuir a la documentación es necesario tener el repositorio actualizado, para ello se debe ejecutar los siguientes comandos:
Comando para ubicarse en la carpeta donde se encuentra el repositorio cd /opt/Development/Workspace/docs
Comando para traer los cambios del repositorio de ERPyA git fetch upstream
Comando para reemplazar el repositorio en mi cuenta por el repositorio de ERPyA git rebase -f upstream/master
Si da conflicto o se necesitan los cambios de una rama en especifico, se debe ajecutar el siguiente comando
git merge masterHacer commit para corregir el conflicto.
Note
No se debe trabajar en la rama master.
Actualizar el Servicio de Prueba
Hacer commit en la rama creada para el documento.
Ubicarse en 159.65.189.53:8000/projects/documentacion-uestandar/builds/ o en su defecto http://docs.erpya.com/projects/documentacion-uestandar/builds/
Seleccione la rama (versión) a actualizar.
Seleccione la opción “Versión de Compilación”.
Note
La palabra “documentacion-uestandar” corresponde al proyecto creado en la documentación Crear un Proyecto en Read the Docs:
Espere el resultado
Compilando: Se esta compilando el servicio y construyendo los cambios.
Fallido: Ocurrio un error y no se compilo el servicio de prueba. En este caso debe realizar lo siguiente:
Seleccione la palabra “Fallido” para ver el error.
Solucione el error y genere otro commit con los cambios para solucionarlo.
Realice el proceso para “Actualizar el Servicio de Prueba”.
Con Éxito: Se compilo exitosamente el servicio de prueba.
Ubique el servicio de prueba 159.65.189.53:8000/docs/documentacion-uestandar/en/versióncompilada o en su defecto puede seleccionar la opción “Ver Documentación” y cambie en la url http://docs.erpya.com/docs/documentacion-uestandar/en/latest/ la palabra “latest” por el nombre de la versión compilada.
Refresque o Actualice la página para ver los cambios.