Agregar imágenes y logo

Esta guía explica cómo incluir imágenes dentro de tu documentación y cómo añadir un logo personalizado en la barra lateral del sitio generado con Sphinx.

1. Agregar imágenes en Markdown

Estructura recomendada

Tu proyecto Sphinx podría verse así:

docs/
├── source/
│   ├── _static/
│   │   └── logo.png
│   ├── guia/
│   │   ├── uso.md
│   │   └── imagenes/
│   │       └── ejemplo.png
│   ├── index.md
│   └── conf.py
└── Makefile

Sintaxis básica de Markdown

![Texto alternativo](imagenes/ejemplo.png)

⚠️ Usa rutas relativas al archivo .md donde insertás la imagen.

Usar la directiva `{image}` de MyST

Permite controlar el tamaño, alineación y texto alternativo:

```{image} imagenes/ejemplo.png
:alt: Ejemplo de imagen
:width: 300px
:align: center
```

Opciones útiles:

Parámetro	Descripción
`:alt:`	Texto alternativo
`:width:`	Ancho (px o %)
`:height:`	Alto
`:align:`	`left`, `center`, `right`
`:scale:`	Escala porcentual (por ejemplo `50`)

Usar figuras con pie de imagen

Para mostrar un pie o número de figura, usá {figure}:

```{figure} imagenes/ejemplo.png
:alt: Ejemplo de figura
:width: 400px
:align: center

**Figura 1.** Ejemplo con pie de imagen.
```

2. Usar `_static` para imágenes globales

Sphinx trata _static/ como el lugar oficial para recursos (CSS, JS, imágenes globales).

Ejemplo:

docs/source/_static/logo.png

Luego, en Markdown:

![Logo del proyecto](_static/logo.png)

O bien:

```{image} _static/logo.png
:alt: Logo del proyecto
:width: 150px
:align: right
```

3. Configuración en `conf.py`

Asegurate de tener:

html_static_path = ["_static"]

Podés agregar más rutas si querés:

html_static_path = ["_static", "imagenes"]

4. Enlaces a imágenes externas

También podés usar URLs completas:

![Logo de Python](https://www.python.org/static/community_logos/python-logo.png)

⚠️ No recomendado si querés que la documentación funcione offline.

5. Agregar un logo al tema HTML (barra lateral)

Podés mostrar tu logo en la barra lateral (por ejemplo, en sphinx_rtd_theme o furo).

Paso 1: Guardar el logo

Colocá tu archivo en:

docs/source/_static/logo.png

Paso 2: Configurar `conf.py`

Editá tu conf.py y añadí:

# -- Logo y favicon --
html_logo = "_static/logo.png"     # Logo en la barra lateral
html_favicon = "_static/logo.png"  # Icono del navegador (opcional)

Para sphinx_rtd_theme (Read the Docs theme), asegurate de que esté instalado:

pip install sphinx-rtd-theme

y configuralo así:

html_theme = "sphinx_rtd_theme"
html_theme_options = {
    "logo_only": True,       # Mostrar solo el logo sin texto
    "display_version": False # Ocultar versión del proyecto (opcional)
}

💡 Si no ponés logo_only: True, Sphinx mostrará el logo junto al título del proyecto.

Paso 3: Reconstruir la documentación

make html

o

sphinx-build -b html source _build/html

Luego abrí _build/html/index.html en tu navegador:
→ el logo aparecerá en la barra lateral.

6. Solución de problemas

Problema	Causa probable	Solución
La imagen no aparece	Ruta incorrecta	Verificá la ruta relativa al archivo `.md`
“image not found”	Carpeta fuera de `source/`	Mové la imagen dentro de `source/` o `_static/`
Logo no visible	Ruta errónea o `html_logo` mal definido	Revisá `conf.py`
Imagen gigante	Faltó `:width:` o CSS personalizado	Usá `:width:` en `{image}`