Documentación con MkDocs

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.

Imagen de cabecera: Sigmund en Unsplash