Guía para documentar CfdiUtils

En esta guía conocerás lo básico para crear y modificar la documentación para la librería

Ubicación de la documentación

La documentación se encuentra publicada en https://cfdiutils.readthedocs.org.

Los archivos fuente de la documentación están en la carpeta docs/ y además se apoya de los archivos mkdocs.yml y .markdownlint.json.

La documentación es compilada (o transformada, o como le quieras decir) utilizando la herramienta mkdocs.

Si deseas realizar un cambio en la documentación realiza el proceso normal de cualquier cambio en GitHub (fork, pull, push & pull-request).

No somos expertos ni en ReadTheDocs ni en mkdocs, así que si tienes experiencia cuéntanos cómo podemos mejorar el proyecto y su integración.

Reglas

• La documentación se debe escribir en español con excepción del archivo CHANGELOG.md
• Términos como XML, XSD, XSLT se escriben en mayúsculas.
• Los archivos van escritos en minúsculas y estructurados en grupo, a excepción de TODO.md y CHANGELOG.md
• Todos los nombres de funciones, clases, propiedades, métodos, etc. deben escribirse con ` (acento grave)
• Se debe cumplir con la sintaxis de markdown aceptada por markdownlint, excepto:
  • Se puede usar la longitud de línea que sea
  • Se admiten hasta dos NEW_LINE seguidos
  • Los encabezados (headings) pueden acabar con signo de admiración e interrogación
  • Mira el archivo .markdownlint.json

Flujo de trabajo

Estas herramientas te ayudarán para realizar la documentación y no tener problemas de construcción:

• mkdocs: Usada para previsualizar los cambios.
• markdownlint: Revisión de la sintaxis.
• git: Control de cambios.

Descargar el proyecto

La documentación del proyecto se encuentra en el repositorio de CfdiUtils en la carpeta docs/ y sus cambios serán aprobados usando un pull request tradicional. Si va a agregar nuevas páginas debe agregarlas al archivo mkdocs.yml en la carpeta base del proyecto.

git clone https://github.com/eclipxe13/cfdiutils

Realizar cambios

Puedes observar los cambios en el navegador mientras suceden, esto abre un puerto en tu equipo que puedes consultar en el navegador, por ejemplo: http://127.0.0.1:8000/

mkdocs serve

Realiza tus cambios, te recomiendo usar alguno de los editores que tienen soporte para markdownlint, puedes encontrar una lista en https://github.com/DavidAnson/markdownlint#related

Revisión de cambios

Antes de publicar, verifica tus cambios, si alguno de estos comandos falla entonces Travis-CI fallará

markdownlint *.md docs/
mkdocs build --strict --site-dir build/docs

Publicación de cambios

Si no estás acostumbrado a contribuir usando GitHub te recomiendo ver las guías (externas):

• Clone y Fork con git y GitHub
• Pull request en GitHub

Instalación de markdownlint

El proyecto cuenta con un archivo package.json que contiene la dependencia de markdownlint-cli, por lo que si no lo tienes instalado globalmente lo único que tendrías que hacer para instalarlo en el proyecto es:

npm install

Y ejecutar el programa como se muestra en el flujo de trabajo.

node node_modules/markdownlint-cli/markdownlint.js

Instalación de mkdocs

Revisa la página https://www.mkdocs.org/#installation.

En Debian GNU/Linux y derivados lo puedes instalar usando:

apt-get install mkdocs

También se puede utilizar el administrador de paquetes de python. El parámetro --user es para instalarlo en espacio de trabajo del usuario.

pip install --user mkdocs

En MS Windows... uhm... chocolalety

choco install mkdocs