Skip to main content
Editar en GitHub (EN)

Flujo de trabajo de documentación 📚

Esta guía trata sobre cómo redactar, crear y mantener la documentación de los proyectos Ultralytics.

Estructura de la documentación 🗂️

Principales sitios web 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 al grano
  • Voz activa: «Entrenar el modelo», no «El modelo está entrenado»
  • Ejemplos de código: Mostrar código funcional para cada concepto
  • Materiales visuales: Utiliza imágenes o diagramas cuando sea útil
  • Formato uniforme: Sigue las estructuras de página existentes

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 archivos multimedia

Guardar en el repositorio o utilizar una CDN:

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

Keep image sizes reasonable (<500KB when possible).

Documentación de construcción 🔨

Desarrollo local

Instalar las dependencias:

pip install -e ".[docs]"

Crear y ofrecer a nivel local:

mkdocs serve

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

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. Consulte el 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:

  • Breve descripción: Resumen en una línea
  • Argumentos: Descripciones de los parámetros con sus tipos
  • Devoluciones: Descripción del valor de retorno
  • Ejemplos: Ejemplo de código funcional

Añadir nuevas páginas 📄

1. Crear Markdown

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

2. Actualizar la navegación

Editar mkdocs.yml:

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

3. Redactar contenido

Sigue la guía de estilo e incluye ejemplos.

4. Compilación de prueba

mkdocs serve

5. Enviar solicitud de incorporación de cambios

Seguir flujo de trabajo de desarrollo para el proceso de relaciones públicas.

Traducciones 🌐

Añadir traducciones

  1. Copiar English al directorio de idiomas:
cp docs/en/page.md docs/zh/page.md

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

  2. Actualización mkdocs.yml enlaces alternativos

Directrices de traducción

  • Mantén los términos técnicos en English YOLO, mAP, FPS)
  • Traducir descripciones y explicaciones
  • Mantener la misma estructura que en English
  • Actualizar las traducciones cuando cambie English

Documentación de CI 🤖

CI automáticamente:

  • Genera documentación con cada solicitud de incorporación de cambios
  • Comprueba si hay enlaces rotos
  • Valida markdown
  • Se implementa en el entorno de producción al fusionar con la rama principal

Solución de errores de compilación

Problemas habituales:

  • Enlaces rotos: Corregir o eliminar los enlaces no válidos
  • Imágenes que faltan: Añadir imágenes o actualizar las rutas
  • YAML no válido: Corregir la sintaxis del frontmatter
  • Errores de los complementos: Comprueba la configuración del complemento

Buenas prácticas ✅

Organización del contenido

  • Estructura lógica: Contenido relacionado con el grupo
  • Divulgación progresiva: Básico → avanzado
  • Reticulación: Enlace a páginas relacionadas
  • Optimización para motores de búsqueda: Utiliza títulos y descripciones claros

Mantenimiento

  • Mantente al día: Actualización con nuevas funciones
  • Eliminar lo obsoleto: Eliminar contenido obsoleto
  • Comprueba los enlaces: Corrige los enlaces rotos con regularidad
  • Comentarios de los usuarios: Responder a las preguntas más frecuentes

Accesibilidad

  • Texto alternativo: Describe las imágenes para los lectores de pantalla
  • Borrar encabezados: Utiliza una jerarquía adecuada de encabezados
  • Lenguaje sencillo: Evita el uso de jerga siempre que sea posible
  • Contraste de códigos: Asegúrate de que los bloques de código sean legibles

Recursos 📚