YOLO Vision 2026:

Flujo de trabajo de la documentación 📚#

Esta guía cubre la redacción, compilación y mantenimiento de la documentación para los proyectos de Ultralytics.

Estructura de la documentación 🗂️#

Sitios principales de documentación#

Estructura del repositorio#

docs/
├── en/              # English docs
│   ├── index.md     # Homepage
│   ├── guides/      # User guides
│   ├── tasks/       # Task-specific docs
│   ├── models/      # Model documentation
│   └── reference/   # API reference
├── zh/              # Chinese translations
└── overrides/       # Theme customizations

Redacción de la documentación ✍️#

Guía de estilo#

  • Claro y conciso: Ve al grano rápidamente
  • Voz activa: "Entrena el modelo" en lugar de "El modelo es entrenado"
  • Ejemplos de código: Muestra código funcional para cada concepto
  • Ayudas visuales: Utiliza imágenes y diagramas cuando sea útil
  • Formato consistente: 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

### Code Examples

- **Minimal**: Show only relevant code
- **Runnable**: Examples should work copy-paste (test with actual [YOLO models](https://docs.ultralytics.com/models))
- **Commented**: Explain non-obvious parts
- **Tested**: Verify examples work with current version

```python
from ultralytics import YOLO

# Load pretrained model
model = YOLO("yolo26n.pt")

# Train on custom data
results = model.train(data="coco8.yaml", epochs=3)
```

Imágenes y multimedia#

Almacénalas en el repositorio o usa un CDN:

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

Mantén los tamaños de imagen en un rango razonable (<500 KB cuando sea posible).

Compilación de la documentación 🔨#

Desarrollo local#

Instala las dependencias:

pip install -e ".[docs]"

Compila y sirve localmente:

mkdocs serve

Visita http://127.0.0.1:8000 para previsualizar.

Configuración de MkDocs#

Configuración principal en mkdocs.yml:

site_name: Ultralytics Docs
theme:
    name: material
    palette:
        - scheme: slate
plugins:
    - search
    - ultralytics

Documentación de la API 📖#

La referencia de la API se genera automáticamente a partir de las cadenas de documentación (docstrings). Consulta la referencia de la API completa para 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 de una línea
  • Args: Descripciones de los parámetros con sus tipos
  • Returns: Descripción del valor de retorno
  • Examples: Ejemplo de código funcional

Adición de nuevas páginas 📄#

1. Crea el archivo Markdown#

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

2. Actualiza la navegación#

Edita mkdocs.yml:

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

3. Escribe el contenido#

Sigue la guía de estilo e incluye ejemplos.

4. Prueba la compilación#

mkdocs serve

5. Envía el PR#

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

Traducciones 🌐#

Adición de traducciones#

  1. Copia la versión en inglés al directorio de idiomas:
cp docs/en/page.md docs/zh/page.md

  1. Traduce el contenido y mantén los ejemplos de código en inglés

  2. Actualiza los enlaces alternativos en mkdocs.yml

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 la documentación 🤖#

El CI realiza automáticamente lo siguiente:

  • Compila la documentación en cada PR
  • Comprueba si hay enlaces rotos
  • Valida el formato de Markdown
  • Despliega a producción al fusionar con main

Corrección de errores de compilación#

Problemas comunes:

  • Enlaces rotos: Repara o elimina los enlaces no válidos
  • Imágenes faltantes: Añade las imágenes o actualiza las rutas
  • YAML no válido: Corrige la sintaxis del frontmatter
  • Errores de plugins: Comprueba la configuración de los plugins

Mejores prácticas ✅#

Organización del contenido#

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

Mantenimiento#

  • Mantén al día: Actualiza para nuevas características
  • Elimina lo obsoleto: Borra el contenido obsoleto
  • Comprueba los enlaces: Revisa los enlaces rotos con regularidad
  • Retroalimentación de usuarios: Aborda las preguntas comunes

Accesibilidad#

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

Recursos 📚#

Colaboradores
GLglenn-jocher5