Crea la documentación de tu proyecto con MkDocs
El mundo de la documentación siempre ha sido una asignatura pendiente en el software libre . Existen muchas herramientas de documentación pero la inserción de dicha documentación se torna bastante engorrosa. Por estos motivos, nació un nuevo lenguaje llamado MarkDown, que se caracteriza por ser muy simple y ligero para el uso de los usuarios.
Este nuevo lenguaje se ha utilizado principalmente en GitHub para generar la documentación de los desarrollos , y a día de hoy en muchas de las webs de aplicaciones se está observando una nueva forma de generar documentación.
Ejemplos:
Esta nueva forma de documentar la podemos utilizar también nosotros para generar la documentación de nuestra propias aplicaciones gracias a la herramienta que vamos a ver a continuación llamada mkdocs.
MKDOCS
La herramienta mkdocs(https://www.mkdocs.org/) es un generador de sitios de documentación bastante sencillo de utilizar y ligero , que permite luego construir la documentación para incluirla en cualquier servidor web. Para ello utiliza el lenguaje MarkDown para construir la propia documentación y el lenguaje YAML para construir el sitio.
Instalación MKDOCS
Para instalarlo es necesario que tengamos python y python-pip instalado como requisito previo. Ya que python normalmente viene instalado por defecto, instalaremos el paquete python-pip (Debian y Ubuntu):
# sudo apt-get install python-pip
Tras instalar las dependencias instalamos la herramienta mkdocs:
# pip install mkdocs
Y ya tendremos la herramienta instalada y lista para usarse! Rápido y sencillo! Primeros pasos: Los primeros pasos son muy sencillos, ya que solamente hay que comenzar iniciando el proyecto con el comando mkdocs new y el nombre del nuevo proyecto de documentación:
# mkdocs new test
INFO - Creating project directory: test
INFO - Writing config file: test/mkdocs.yml
INFO - Writing initial docs: test/docs/index.md
Este paso creará la siguiente estructura de ficheros y directorios:
# tree test/
test/
├── docs ------> Directorio de documentación
│ └── index.md ------> Fichero de contenido MarkDown
└── mkdocs.yml -----> Fichero configurador del sitio
En el fichero mkdocs.yml podemos establecer los parámetros de configuración del sitio web , en él se establecen las diferentes páginas que va a tener de documentación el proyecto, así como el tema y otros parámetros relacionados.
Dentro de directorio docs se crea el fichero index.md que contiene la página principal del sitio.
Vamos a comprobar cómo se visualiza por defecto este gestor de documentación. Si utilizamos mkdocs serve se instancia un servicio web para poder realizar la visualización en la interfaz loopback. Si por casualidad tuviéramos el servidor instalado en otra máquina que no sea la local, con el parámetro -a le establecemos la dirección IP y puerto donde queremos que sirva, como por ejemplo:
# mkdocs serve -a http://192.168.1.201:4444
INFO - Building documentation...
[I 160110 18:17:49 server:271] Serving on http://192.168.1.201:4444
[I 160110 18:17:49 handlers:58] Start watching changes
[I 160110 18:17:49 handlers:60] Start detecting changes
Si accedemos al navegador podemos ver el resultado:
Este servicio web va ser útil de forma temporal para ir viendo los resultados de las modificaciones realizadas a nuestra documentación, ya que por cada modificación de los ficheros MarkDown se vuelve a regenerar el servicio web para refrescar los cambios .
Uno de los aspectos más interesantes de la herramienta es la facilidad con la que cambiar el estilo gracias a los temas que proporciona . Si en el fichero mkdocs.yml le agregamos la variable theme seguido del nombre de los diferentes temas que soporta cambiaremos el estilo de la web para poder adaptarlo a nuestras necesidades, aunque también nos permite crear nuestro propio tema para utilizarlo. Actualmente los temas incluidos en la aplicación se encuentran en el siguiente enlace: https://www.mkdocs.org/user-guide/styling-your-docs/#built-in-themes
CONSTRUIR EL SITIO
Una vez generada una versión final de nuestra documentación y lista para utilizarla, debemos crear el “site”, es decir, los ficheros que se van a introducir en el servidor web. Para ello utilizaremos el comando mkdocs build, que nos creará un nuevo directorio dentro de nuestro proyecto llamado site. Dentro de esta carpeta ya se encuentra la documentación en un formato web para que podamos introducirlo ya sea en el DocumentRoot de Apache o de Nginx, y listo!
Pues bueno, espero que os haya gustado este post de esta fantástica herramienta y que podáis crear vuestras documentaciones de un modo rápido y sencillo.