Ejemplo de documentación python con MKDocs
En uno de mis últimos cursos de python me han preguntado cómo se podía realizar con python la documentación automatizada de una aplicación. Dado que en los proyectos donde he trabajado nunca he tenido que realizar esta tarea personalmente, desconocía la parte práctica. Por lo tanto, he creado este tutorial de ejemplo utilizando MKDocs https://www.mkdocs.org/ y Material for MkDocs https://squidfunk.github.io/mkdocs-material/ como aplicación para la presentación de la misma.
Otra opción para quienes tienen un proyecto open source es utilizar la plataforma Read the Docs que permite crear, alojar y navegar por la documentación mediante la creación de una cuenta (gratuita para proyectos open source) en su portal.
Esta cuenta luego se conectará al repositorio donde está alojada la aplicación (Bitbucket, Github, Gitlab, etc.) y genera la documentación automáticamente a través de unos scripts creados a tal fin. Un completo tutorial lo podéis encontrar en https://docs.readthedocs.io/en/stable/tutorial/index.html y ejemplos en https://docs.readthedocs.io/en/stable/examples.html.
Instalar mkdocs
- Para instalar mkdocs crearemos un proyecto de ejemplo en un ambiente virtual en nuestro ordenador. Abrimos la consola en nuestro Linux y ejecutamos:
python -m venv ejemplo_api/venv
cd ejemplo_api
source venv/bin/activate- Ahora procedemos a instalar mkdocs y material:
python -m pip install mkdocs
python -m pip install "mkdocstrings[python]"
python -m pip install mkdocs-material- El repositorio para descargar los ficheros ejemploAsyncioAPImain.py y ejemploAsyncioAPI.py utilizados este ejemplo se encuentran en https://github.com/fortinux/ejemploDocumentacionPython.
Configurar mkdocs y material
- A continuación creamos los ficheros docs/ejemploAsyncioAPImain.md, docs/ejemploAsyncioAPI.md, mkdocs.yml, y requirements.txt. Abrimos nuestro IDE (integrated development environment) preferido y escribimos en el fichero ejemploAsyncioAPImain.md*
::: ejemploAsyncioAPImain- En docs/ejemploAsyncioAPI.md introducimos:
\# API Reference
::: ejemploAsyncioAPI- En mkdocs.yml:
site_name: Documentación de la aplicación
theme:
name: "material"
plugins:
- mkdocstrings
nav:
- Índice: index.md
- ejemploAsyncioAPImain.md
- ejemploAsyncioAPI.md- Finalmente para construir la documentación utilizamos en primer lugar doctests:
cd docs python -m doctest ejemploAsyncioAPImain python -m doctest ejemploAsyncioAPI - Luego creamos la aplicación web con MKDocs:
mkdocs build mkdocs serve --dev-addr=0.0.0.0:8088
Ya podremos ir al navegador y abrir la dirección http://127.0.0.1:8088 para ver nuestra documentación.
Imagen de portada: Web de MKDocs Material
Si buscas un formador para realizar un curso u otra actividad formativa (webinar, workshops, bootcamps, etc.) en tu organización, me puedes ubicar a través de la página de contacto. Muchas gracias.
Si te ha gustado el artículo puedes ayudarme haciendo una donación con criptomonedas. Gracias!!!