Saltar a contenido

MkDocs

MkDocs Logo

La documentación es una parte esencial de cualquier proyecto de software. Proporciona a los desarrolladores y usuarios una guía sobre cómo usar y entender el código. Una de las herramientas más populares para crear documentación en Python es MkDocs. En este artículo, exploraremos MkDocs en detalle, aprenderemos cómo instalarlo, configurarlo y crear documentación elegante para tu proyecto.

¿Qué es MkDocs?

MkDocs es una herramienta de código abierto que permite crear documentación estática a partir de archivos Markdown. Markdown es un lenguaje de marcado ligero que es fácil de aprender y usar. MkDocs toma estos archivos Markdown y los convierte en un sitio web de documentación listo para ser publicado.

Instalación de MkDocs

Para comenzar a usar MkDocs, primero debes instalarlo en tu sistema. La instalación de MkDocs es sencilla y se realiza a través de pip, el administrador de paquetes de Python. Abre tu terminal y ejecuta el siguiente comando:

pip install mkdocs

Una vez que MkDocs esté instalado, puedes verificar la versión con:

mkdocs --version

Creación de un Nuevo Proyecto MkDocs

Ahora que MkDocs está instalado, puedes crear un nuevo proyecto de documentación. Dirígete a la carpeta raíz de tu proyecto y ejecuta el siguiente comando para crear un nuevo proyecto MkDocs:

mkdocs new my-docs

Esto creará una nueva carpeta llamada my-docs con la estructura básica de un proyecto MkDocs:

my-docs/
    mkdocs.yml
    docs/
        index.md
  • mkdocs.yml: Este archivo de configuración contiene la configuración del proyecto, como el título del sitio y la lista de páginas de documentación.
  • docs/: Esta carpeta es donde colocarás tus archivos Markdown que se convertirán en páginas de documentación.

Configuración de tu Proyecto MkDocs

Abre el archivo mkdocs.yml en tu editor de texto favorito para configurar tu proyecto. Puedes personalizar el título de tu sitio y agregar enlaces a la barra de navegación principal. Por ejemplo:

site_name: Mi Documentación
nav:
  - Principal: index.md
  - Guía de Uso: guia.md

Escritura de Documentación

Comienza a escribir tu documentación en archivos Markdown dentro de la carpeta docs/. Por ejemplo, crea un archivo guia.md y agrega contenido como este:

# Guía de Uso

En esta guía aprenderás cómo utilizar nuestra biblioteca increíblemente útil.

## Instalación

Para comenzar, primero debes instalar la biblioteca. Ejecuta el siguiente comando:

```bash
pip install biblioteca-increible

Uso Básico

Ahora puedes importar la biblioteca en tu código Python y empezar a usarla:

import biblioteca_increible

# Haz cosas asombrosas con la biblioteca

¡Y eso es todo! Has completado la instalación y ahora estás listo para utilizar nuestra biblioteca increíblemente útil. 

## Vista Previa Local

Para ver una vista previa de tu sitio de documentación de MkDocs en tu máquina local, ejecuta el siguiente comando en la terminal desde la carpeta raíz de tu proyecto:

```bash
mkdocs serve

Esto lanzará un servidor de desarrollo local y mostrará la URL donde puedes acceder a tu documentación, por lo general, http://127.0.0.1:8000/.

Generación y Despliegue de la Documentación

Una vez que hayas escrito toda tu documentación, puedes generar el sitio web estático con el siguiente comando:

mkdocs build

Esto creará una carpeta llamada site/ que contiene todos los archivos HTML, CSS y otros recursos necesarios para tu sitio de documentación.

Puedes desplegar tu sitio en una variedad de servicios de alojamiento web, como GitHub Pages, Netlify o cualquier otro servicio que admita sitios web estáticos. Sube la carpeta site/ generada a tu servicio de alojamiento preferido y tu documentación estará en línea y lista para ser compartida.

Temas y Personalización

MkDocs ofrece varios temas predefin

idos para personalizar el aspecto de tu documentación. Puedes configurar el tema en tu archivo mkdocs.yml. También puedes personalizar aún más tu sitio mediante la edición de archivos CSS y HTML según tus necesidades.

Conclusiones

MkDocs es una herramienta poderosa y fácil de usar para crear documentación elegante para tus proyectos. Con su formato simple de Markdown y su capacidad para generar sitios web estáticos, puedes crear documentación de alta calidad en poco tiempo. ¡Así que comienza a documentar tus proyectos y comparte tu conocimiento con el mundo!

Referencias