Este repo contiene un pequeño ejemplo acerca de como mantener un API documentada siempre consistente con el código fuente.
Para ello hace uso de las siguientes herramientas:
- darglint como herramienta de validación de los docstrings
De manera adicional, se hace uso de las siguientes herramientas para la validación y generación de la documentación
- flake8 como herramienta de analisis estático de código. darglint funciona de forma aislada o como plugin de flake8
- Sphinx como motor de documentación.
El repo se basa en un proyecto Poetry que te permite trabajar en un entorno virtual de forma sencilla. Para ello, simplemente ejecuta este comando para empezar a probar
poetry install
Ese comando te creará un entorno virtual, te lo activará y a continuación te instalará las dependencias.
Si quieres hacer un setup sin poetry, la manera más sencilla de probar este repo sería instalarte las dependencias después de crearte un entorno virtual. Algo así como:
pip install darglint flake8 sphinx
El módulo calc
contiene un submodulo dummy el cual implementa cuatro operaciones aritméticas: suma, resta, multiplicación y división. Pero aquí lo de menos es la funcionalidad, sino cómo la documentamos.
Prueba a modificar los docstrings, los parámetros, lo que quieras. Liala parda. Y cuando quieras, ejecuta este comando:
darglint calc
O si quieres validar los docstrings junto con las guidelines del PEP8, usa directamente flake8
flake8 calc
Además de describir los parametros, excepciones, un resumen de lo que hace nuestro lógica de negocio, podemos incluir snippets de uso de nuestras funciones, y ejecutar dicho código como parte de nuestros tests!
Si miras la implementación de las operaciones aritméticas super-avanzadas que se incluyen en este repositorio, verás que incluyen un ejemplo de uso de la función. A la hora de testear, puedes hacer uso de la opcion --doctest-modules
de pytest para chequear esos snippets.
Tienes muchas opciones para efectuar las comprobaciones anteriores sobre tu código, pero aqui te dejo un par de ideas:
- En el ciclo de Integración continua, ejecuta el comando de arriba para verificarlo. O mucho mejor,
- Usando la herramienta pre-commit que ejecute el chequeo antes de comitear cambios en tu rama. Tienes una configuracion para pre-commit en este mismo repositorio.
> pre-commit install
pre-commit installed at .git/hooks/pre-commit
Cuando los hooks esten instalados, al hacer commit o push verás algo como esto
> git commit -m "Added a new awesome change"
[WARNING] Unstaged files detected.
[INFO] Stashing unstaged files to /home/japizarro/.cache/pre-commit/patch1632760228-11911.
Trim Trailing Whitespace.................................................Passed
Fix End of Files.........................................................Passed
Check Yaml...............................................................Passed
Check for added large files..............................................Passed
flake8...................................................................Passed
Cuando alguno de los comandos anteriores falle, arregla lo que sea necesario. Una vez este listo, genera la documentación con el siguiente comando:
make -C docs -b doctest html
Observa el flag -b doctest
. Esto hará que se chequeen los doctest incluidos en la documentación :D.
Y tendrás el site html con la documentación de esta estupenda calculadora en docs/build/html
;)