Mkdocs-Plugging

MkDocs es una excelente herramienta para crear documentaciones limpias y sencillas, pero en ocasiones, necesitas características adicionales para hacer que tu documentación sea aún más efectiva. Las extensiones de MkDocs son complementos que te permiten agregar funcionalidades personalizadas a tu sitio de documentación. En este artículo, exploraremos tres extensiones populares: mkdocstrings, mkdocs-bibtex, y neoteroi-mkdocs. Veremos cómo instalar y utilizar estas extensiones, junto con ejemplos prácticos de su funcionalidad.

1. mkdocstrings

mkdocstrings es una extensión de MkDocs que genera documentación automáticamente a partir de docstrings en el código fuente de Python. Esto es especialmente útil para documentar bibliotecas y módulos de Python de una manera coherente y mantenible.

Instalación

Para instalar mkdocstrings, ejecuta el siguiente comando:

pip install mkdocstrings

Configuración

Agregar mkdocstrings a tu configuración de MkDocs es sencillo. En tu archivo mkdocs.yml, agrega el siguiente complemento:

plugins:
  - mkdocstrings

Uso

A continuación, proporcionamos un ejemplo de cómo documentar una función Python y luego generar la documentación con mkdocstrings:

# mymodule.py

def add_numbers(a, b):
    """
    Esta función suma dos números.

    Args:
        a (int): El primer número.
        b (int): El segundo número.

    Returns:
        int: La suma de a y b.
    """
    return a + b

Una vez que hayas agregado docstrings a tu código, puedes ejecutar el siguiente comando para generar la documentación:

mkdocs serve

La documentación se generará automáticamente y estará disponible en tu sitio MkDocs local.

2. mkdocs-bibtex

mkdocs-bibtex es una extensión que te permite incluir citas bibliográficas y referencias en tu documentación. Esto es útil cuando necesitas respaldar tus afirmaciones con fuentes académicas o proporcionar créditos adecuados.

Instalación

Para instalar mkdocs-bibtex, ejecuta el siguiente comando:

pip install mkdocs-bibtex

Configuración

Agrega mkdocs-bibtex a tu configuración de MkDocs en mkdocs.yml:

plugins:
  - search
  - mkdocs-bibtex

Uso

Para incluir una cita bibliográfica en tu documentación, puedes usar un marcador especial en tu archivo Markdown:

{% bibtex key %}

Luego, en tu archivo mkdocs.yml, define la referencia utilizando el siguiente formato:

extra:
  bibtex_bibfiles:
    - references.bib

Asegúrate de tener un archivo references.bib con tus citas bibliográficas en la misma carpeta que tu proyecto.

3. neoteroi-mkdocs

neoteroi-mkdocs es una extensión que agrega una serie de mejoras y características adicionales a MkDocs. Esto incluye soporte para tablas de contenido expandibles, numeración de secciones, índices y más.

Instalación

Para instalar neoteroi-mkdocs, ejecuta el siguiente comando:

pip install mkdocs-neoteroi

Configuración

Agrega neoteroi-mkdocs a tu configuración de MkDocs en mkdocs.yml:

plugins:
  - search
  - neoteroi

Uso

neoteroi-mkdocs agrega varias características útiles a tu documentación, como tablas de contenido plegables. Aquí hay un ejemplo de cómo usarlo:

## Sección 1
<details>
<summary>Ver contenido</summary>

Contenido de la sección 1.

</details>

## Sección 2
<details>
<summary>Ver contenido</summary>

Contenido de la sección 2.

</details>

Las secciones estarán plegadas por defecto y los usuarios podrán expandirlas para ver su contenido.

Conclusión

Las extensiones de MkDocs pueden mejorar significativamente la calidad y funcionalidad de tu documentación. Ya sea que necesites documentar automáticamente tus módulos de Python, agregar citas bibliográficas o mejorar la experiencia general de tus lectores, estas extensiones te proporcionan las herramientas necesarias para hacerlo de manera efectiva. ¡Explora estas extensiones y eleva tu documentación al siguiente nivel!

Referencias

• Repositorio de mkdocstrings: https://github.com/pawamoy/mkdocstrings
• Repositorio de mkdocs-bibtex: https://github.com/hristo-ivanov/mkdocs-bibtex
• Repositorio de neoteroi-mkdocs: https://github.com/neoteroi/mkdocs

Esperamos que esta guía te ayude a aprovechar al máximo estas extensiones de MkDocs y a crear documentación de alta calidad. ¡Disfruta documentando tu proyecto!