Ultralytics YOLO27: Únete a la lista de espera.
Get Started

Flujo de trabajo de documentación 📚#

Esta guía explica cómo redactar, generar y mantener la documentación de los proyectos de Ultralytics.

Estructura de la documentación 🗂️#

Sitios principales de documentación#

Estructura del repositorio#

La propiedad del contenido y las familias de páginas varían según el repositorio. Sigue la jerarquía y el manifiesto de navegación existentes en lugar de dar por sentado que hay un conjunto fijo de carpetas. Un árbol de fuentes típico empieza así:

docs/
└── en/              # Source content

Redacción de documentación ✍️#

Guía de estilo#

  • Claro y conciso: Ve al grano rápidamente
  • Voz activa: «Entrena el modelo», no «El modelo se entrena»
  • Ejemplos de código: Muestra código funcional para cada concepto
  • Recursos visuales: Usa imágenes o diagramas cuando sean útiles
  • Formato coherente: Sigue las estructuras de página existentes

Formato Markdown#

---
description: Brief page description for SEO
keywords: relevant, keywords, for, search
---

# Page Title

Brief introduction explaining what this page covers.

## Section Heading

Content with examples:

```python
from ultralytics import YOLO

# Load pretrained model
model = YOLO("yolo26n.pt")
results = model("image.jpg")
```

### Key points:

- Use bullet points for lists
- Keep paragraphs short
- Include links to related pages

Ejemplos de código#

  • Mínimos: Muestra solo el código pertinente
  • Ejecutables: Los ejemplos deben funcionar al copiarlos y pegarlos (pruébalos con modelos YOLO reales)
  • Con comentarios: Explica las partes que no sean evidentes
  • Probados: Comprueba que los ejemplos funcionan con la versión actual
from ultralytics import YOLO

# Cargar un modelo preentrenado
model = YOLO("yolo26n.pt")

# Entrenar con datos personalizados
results = model.train(data="coco8.yaml", epochs=3)

Imágenes y contenido multimedia#

Guárdalos en el repositorio o usa una CDN:

![Alt text](https://path/to/image.png)

Procura que el tamaño de las imágenes sea razonable (<500KB cuando sea posible).

Generación de la documentación 🔨#

Desarrollo local#

Cada repositorio documenta su propia configuración del entorno. Para este repositorio del manual, instala las dependencias con:

uv pip install -r requirements.txt

Genera y sirve la documentación localmente:

zensical serve

Visita http://127.0.0.1:8000 para ver una vista previa.

Configuración de Zensical#

Los repositorios utilizan un manifiesto de transición compatible con Zensical, mkdocs.yml. Para ver la configuración actual de este repositorio, consulta el archivo mkdocs.yml en la raíz.

Documentación de la API 📖#

La referencia de la API se genera automáticamente a partir de las cadenas de documentación. Consulta la referencia completa de la API para ver todos los módulos:

def train(self, data, epochs=100, batch=16):
    """
    Train the model on a dataset.

    Args:
        data (str): Path to data YAML file
        epochs (int): Number of training epochs
        batch (int): Batch size

    Returns:
        (Results): Training results

    Examples:
        ```python
        model = YOLO("yolo26n.pt")
        results = model.train(data="coco8.yaml", epochs=100)
        ```
    """

Elementos clave:

  • Descripción breve: Resumen en una línea
  • Args: Descripciones de los parámetros con sus tipos
  • Returns: Descripción del valor devuelto
  • Examples: Ejemplo de código funcional

Añadir páginas nuevas 📄#

1. Crear un archivo Markdown#

# Create new guide
touch docs/en/guides/new-guide.md

2. Actualizar la navegación#

Edita mkdocs.yml:

nav:
    - Home: index.md
    - Guides:
          - New Guide: guides/new-guide.md

3. Redactar el contenido#

Sigue la guía de estilo e incluye ejemplos.

4. Probar la compilación#

zensical build --strict

5. Enviar una PR#

Sigue el flujo de trabajo de desarrollo para conocer el proceso de PR.

Traducciones 🌐#

Las traducciones se generan a partir del contenido en inglés durante la compilación centralizada de producción. No añadas manualmente directorios de fuentes traducidas.

Pautas de traducción#

  • Mantén los términos técnicos en inglés (YOLO, mAP, FPS)
  • Traduce las descripciones y explicaciones
  • Mantén la misma estructura que la versión en inglés
  • Actualiza las traducciones cuando cambie la versión en inglés

CI de documentación 🤖#

CI realiza automáticamente estas tareas:

  • Ejecuta zensical build --strict en cada PR
  • Comprueba si hay enlaces rotos
  • Valida el formato Markdown
  • Activa la compilación centralizada de producción tras una fusión en main

Solución de errores de compilación#

Problemas habituales:

  • Enlaces rotos: Corrige o elimina los enlaces no válidos
  • Imágenes que faltan: Añade las imágenes o actualiza las rutas
  • YAML no válido: Corrige la sintaxis del frontmatter
  • Errores de configuración: Comprueba el manifiesto compatible con Zensical

Buenas prácticas ✅#

Organización del contenido#

  • Estructura lógica: Agrupa el contenido relacionado
  • Revelación progresiva: De lo sencillo a lo avanzado
  • Enlaces cruzados: Enlaza páginas relacionadas
  • Optimización para búsquedas: Usa títulos y descripciones claros

Mantenimiento#

  • Mantén el contenido actualizado: Adáptalo a las nuevas funciones
  • Elimina lo obsoleto: Borra el contenido obsoleto
  • Revisa los enlaces: Corrige periódicamente los enlaces rotos
  • Comentarios de usuarios: Responde a las preguntas frecuentes

Accesibilidad#

  • Texto alternativo: Describe las imágenes para los lectores de pantalla
  • Encabezados claros: Usa una jerarquía de encabezados adecuada
  • Lenguaje sencillo: Evita la jerga siempre que sea posible
  • Contraste del código: Asegúrate de que los bloques de código sean legibles

Recursos 📚#

Colaboradores
GLglenn-jocher6LAlaodouya1PDpderrenger1