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 buildLos archivo se generarán en la ruta especificada en el parámetro "site_dir" de la configuración de Mkdocs.
