Editar página en GitHub (EN)

Flujo de trabajo de la documentación 📚

Esta guía cubre la redacción, construcción y mantenimiento de la documentación para 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 documentación ✍️

Guía de estilo

  • Claro y conciso: Ve directo al grano
  • 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: Usa imágenes/diagramas cuando sean útiles
  • 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 medios

Guárdalos en el repositorio o usa un CDN:

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

Mantén tamaños de imagen razonables (<500KB cuando sea posible).

Construcción de la documentación 🔨

Desarrollo local

Instala las dependencias:

pip install -e ".[docs]"

Construye 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 completa de la API 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 en una línea
  • Args: Descripciones de parámetros con sus tipos
  • Returns: Descripción del valor de retorno
  • Examples: Ejemplo de código funcional

Añadir nuevas páginas 📄

1. Crea un 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 construcción

mkdocs serve

5. Envía un PR

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

Traducciones 🌐

Cómo añadir traducciones

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

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

  2. Actualiza los enlaces alternativos en mkdocs.yml

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:

  • Construye la documentación en cada PR
  • Comprueba si hay enlaces rotos
  • Valida el formato de Markdown
  • Despliega en producción al fusionar a la rama principal

Solución de errores de construcció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 del plugin

Mejores prácticas ✅

Organización del contenido

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

Mantenimiento

  • Mantén actualizado: Actualiza para incluir nuevas funciones
  • Elimina lo obsoleto: Borra el contenido desfasado
  • Comprueba enlaces: Repara enlaces rotos regularmente
  • Comentarios de usuarios: Aborda las preguntas frecuentes

Accesibilidad

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

Recursos 📚

Contributors
Editar página en GitHub (EN)
GLglenn-jocher5