Documentar es una parte importante en los proyectos. Normalmente se suele incluir documentación técnica en el propio repositorio usando Markdown (como mínimo el archivo README).
Aunque Markdown es más o menos legible tal cual y por ejemplo Github y compañía lo renderizan automáticamente, hay una manera más eficiente (y bonita) de leer la documentación de un proyecto: MKdocs.
MKdocs es un frontend para archivos Markdown, que permite visualizarlos y navegar entre ellos. Aparte, existe "mkdocs-material", que genera una bonita interfaz usando como base Material Design. Aunque puede usarse por separado, ya sea en nativo o usando docker, en este artículo se hablará del uso de "mkdocs-material" junto a DDEV.
Integración con DDEV
- Crear un archivo `mkdocs.yml` en la raíz del proyecto. Ejemplo de contenido:
site_name: Nombre del proyecto site_author: Solucionex dev_addr: '127.0.0.1:8000' # Información del repositorio del proyecto repo_name: [Nombre del proyecto] repo_url: https://github.com/... # Contenido de la web de documentación. El formato es Título: nombre del archivo. # Las rutas son relativas a la carpeta "docs" de la raíz del proyecto. nav: - Home: index.md - Drush: drush.md # Se permiten múltiples niveles de carpetas. - Tema: - Componentes: theme/components.md - Estilos: theme/styles.md # Este parámetro controla dónde se crearán los archivos estáticos. site_dir: [CARPETA DONDE SE ENCUENTRA EL ARCHIVO index.php]/docs site_url: [URL DE LA WEB DEL PROYECTO]
- Crear un archivo `docker-compose.mkdocs.yml` en la carpeta `.ddev` con el siguiente contenido:
version: '3.6'
services:
# Nombre del servicio.
mkdocs:
# Nombre del contenedor estilo DDEV.
container_name: ddev-${DDEV_SITENAME}-mkdocs
# Imagen de docker de mkdocs-material.
image: squidfunk/mkdocs-material
# Puerto por defecto para el servidor de mkdocs.
ports:
- 8000
# Mapear la carpeta que contiene el archivo mkdocs.yml.
# Cambiar si es necesario.
volumes:
- ../:/docs
# Etiquetas necesarias para que DDEV descubra el contenedor.
labels:
com.ddev.site-name: ${DDEV_SITENAME}
com.ddev.approot: $DDEV_APPROOT
# Variables de entorno, cambiar los puertos si es necesario.
environment:
- VIRTUAL_HOST=$DDEV_HOSTNAME
- HTTP_EXPOSE=9001:8000
- HTTPS_EXPOSE=8001:8000
- Reiniciar DDEV: "ddev restart"
Una vez se ha hecho esto, mkdocs crea automáticamente la web con lka documentación, accesibles desde https://[PROYECTO].ddev.site:[PUERTO ELEGIDO]
Generar sitio estático
Si se quiere generar el sitio estático a partir del contenido actual de la documentación, puede hacerse desde la raíz del proyecto con el siguiente comando:
docker run --rm squidfunk/mkdocs-material -v ./:/docs mkdocs build
Los archivo se generarán en la ruta especificada en el parámetro "site_dir" de la configuración de Mkdocs.
