Ultralytics YOLO27:

Flujo de trabajo de la documentación 📚#

Esta guía explica cómo redactar, crear 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 código fuente típico comienza así:

docs/
└── en/              # Source content

Redacción de la 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

### 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 contenido multimedia#

Guárdalos en el repositorio o usa una CDN:

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

Mantén un tamaño razonable para las imágenes (<500KB cuando sea posible).

Creació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

Crea y sirve localmente:

zensical serve

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

Configuración de Zensical#

Actualmente, los repositorios utilizan un manifiesto transitorio compatible con Zensical: 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. 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 de 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 el PR#

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

Traducciones 🌐#

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

Directrices 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 🤖#

La CI realiza automáticamente lo siguiente:

  • Ejecuta zensical build --strict en cada PR
  • Comprueba si hay enlaces rotos
  • Valida el formato Markdown
  • Activa la compilación de producción centralizada después de fusionar cambios en main

Corrección de errores de compilación#

Problemas habituales:

  • Enlaces rotos: Corrige o elimina los enlaces no válidos
  • Imágenes ausentes: Añade imágenes o actualiza las rutas
  • YAML no válido: Corrige la sintaxis del front matter
  • 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 a páginas relacionadas
  • Optimización para búsquedas: Usa títulos y descripciones claros

Mantenimiento#

  • Mantén el contenido actualizado: Actualízalo para incluir funciones nuevas
  • Elimina lo obsoleto: Borra el contenido obsoleto
  • Comprueba los enlaces: Corrige los enlaces rotos con regularidad
  • Comentarios de los usuarios: Responde a las preguntas habituales

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 cuando sea posible
  • Contraste del código: Asegúrate de que los bloques de código sean legibles

Recursos 📚#

Colaboradores
GLglenn-jocher6PDpderrenger1