Como añadir MKdocs a Ddev para la documentación del proyecto

Cuando trabajamos en un proyecto la documentación es muy importante y algo que normalmente se descuida. Pero más importante que tenerla, es centralizarla o tenerla fácilmente accesible. 

Normalmente la documentación se mantiene en algún lugar online como Confluence, o también algo mínimo en un archivo README en el mismo proyecto. Confluence es muy bueno para proyectos grandes cuando mucha gente tiene que interactuar, y los README son buenos cuando es un proyecto pequeño o se quiere dar información de introducción al proyecto. Pero por lo general no suelen ser la mejor opción para documentación técnica que únicamente van a usar los propios desarrolladores del proyecto, y aunque herramientas como Confluence suelen ser el mejor lugar, no siempre es el idóneo.

¿Qué es MKdocs?

MKdocs es una herramienta que nos facilita la creación, organización y lectura de nuestra documentación. Nos permite organizar la documentación del proyecto dentro del mismo proyecto (o en algún lugar aparte) para tenerla disponible fácilmente. Es muy fácil de configurar gracias al formato YAML, está muy bien documentado y dispone de plugins para poder extenderlo.

La documentación de MKdocs se crea con archivos markdown y es muy fácil de gestionar, además gracias a los repositorios podemos versionarla y tener un histórico de quien ha realizado las modificaciones, y si seguimos un gitflow de usar los pull request también se puede revisar antes de meterla en la rama principal.

¿Porque usar MKdocs con Ddev?

Pues la razon es muy simple, documentar el proyecto y tener todo integrado. Y es que Ddev es una herramienta fantastica para trabajar en local y si ademas podemos tener toda la documentación del proyecto ya sea tecnica o no, disponible facilmente dentro del mismo proyecto, pues utilizar MKdocs junto con Ddev se convierte en una muy buena idea.

¿Como añadir MKdocs a nuestro proyecto Ddev?

Esto es extremadamente simple, y es que gracias al sistema de extensión de servicios del que dispone Ddev, podemos utilizar los que ha creado la propia comunidad (o crear nosotros mismos nuestros servicios).

Y es que en Ddev disponemos el comando "ddev get" para indicarle que paquete queremos descargar, además tenemos algunas opciones extra como "--list", la cual nos permite listar todos los paquetes oficiales disponibles. Pero adicionalmente disponemos de la opción "--all", y si la ejecutamos con "--list", nos devolverá todos los paquetes disponibles, oficiales y de la comunidad.

$ ddev get --list --all

De modo que si ejecutamos el comando anterior podremos ver todos los paquetes que tenemos para descargar, los oficiales que están mantenidos por el propio equipo de Ddev, y los de la comunidad, a los cuales cualquiera puede aportar su propio paquete.

Si miramos todos los paquetes nos encontraremos con uno, el cual nos permite utilizar MKdocs junto a nuestro proyecto que usar ddev, ese comando es el siguiente:

$ ddev get nireneko/ddev-mkdocs

Y listo, una vez ejecutemos ese comando, ya tendremos todo lo necesario para utilizar MKdocs en nuestro proyecto, únicamente nos falta reiniciar Ddev para que descargue la imagen y prepare el contenedor.

$ ddev restart

Y con esto, ya podremos acceder a nuestro MKdocs en el puerto 8001 de nuestro proyecto (si tenemos problemas para acceder podemos usar el comando "ddev describe"). Tenemos que darnos cuenta de que disponemos ahora de una carpeta llamada "mkdocs" en la raíz de nuestro proyecto, dentro un archivo llamado mkdocs.yml en el cual podremos configurar a nuestro gusto el MKdocs local, y dentro una carpeta "docs" con un archivo index.md, el cual es el índice de nuestra documentación.

Para más información lo mejor es acceder a la documentación de esta extension de la comunidad para Ddev, además de la documentación oficial de MKdocs e incluso a la de MKdocs Material, y es que esa extension utilizar un fork de MKdocs para añadirle más funcionalidades y extras.