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.
