Acceder al contenido principal

Documentación con MkDocs

Volver a Blog

Documentación con MkDocs

11 Nov 022
imagen cabecera artículo documentación mkdocs
avatar

DDEV , Documentación ,

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

Comentarios

Añadir nuevo comentario