Ir al contenido

Flujo de trabajo de documentación 📚

Esta guía cubre la escritura, la construcción y el 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

Escribir documentación ✍️

Guía de estilo

  • Claro y conciso: Vaya al grano rápidamente
  • Voz activa: "Entrena el modelo" y no "El modelo es entrenado"
  • Ejemplos de código: Muestre código funcional para cada concepto
  • Ayudas visuales: Utilice imágenes/diagramas donde sea útil
  • Formato consistente: Siga 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("yolo11n.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/yolo11/))
- **Commented**: Explain non-obvious parts
- **Tested**: Verify examples work with current version

```python
from ultralytics import YOLO

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

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

Imágenes y multimedia

Almacenar en el repositorio o utilizar CDN:

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

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

Construcción de documentación 🔨

Desarrollo local

Instalar dependencias:

pip install -e ".[docs]"

Construir y servir 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 cadenas de documentación. Consulte 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("yolo11n.pt")
        results = model.train(data="coco8.yaml", epochs=100)
        ```
    """

Elementos clave:

  • Breve descripción: Resumen de una línea
  • Args: Descripciones de los parámetros con 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. Actualizar la navegación

Editar mkdocs.yml:

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

3. Escribir contenido

Sigue la guía de estilo e incluye ejemplos.

4. Probar la compilación

mkdocs serve

5. Enviar PR

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

Traducciones 🌐

Añadir traducciones

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

  1. Traducir el contenido, mantener los ejemplos de código en English

  2. Actualizar mkdocs.yml enlaces alternativos

Directrices de traducción

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

CI de documentación 🤖

CI automáticamente:

  • Crea la documentación en cada PR
  • Comprueba si hay enlaces rotos
  • Valida el formato markdown
  • Se implementa en producción al fusionarse con la rama principal.

Corrección de errores de compilación

Problemas comunes:

  • Enlaces rotos: Corregir o eliminar enlaces no válidos
  • Imágenes faltantes: Añadir imágenes o actualizar las rutas
  • YAML no válido: Corregir la sintaxis del frontmatter
  • Errores de plugin: Comprobar la configuración del plugin

Mejores prácticas ✅

Organización del contenido

  • Estructura lógica: Agrupar contenido relacionado
  • Divulgación progresiva: De lo simple → a lo avanzado
  • Enlace cruzado: Enlazar a páginas relacionadas
  • Optimización de búsqueda: Utilizar títulos y descripciones claros

Mantenimiento

  • Mantener actualizado: Actualizar para las nuevas características
  • Eliminar lo obsoleto: Borrar el contenido en desuso
  • Comprobar enlaces: Corregir los enlaces rotos regularmente
  • Comentarios de los usuarios: Abordar preguntas comunes

Accesibilidad

  • Texto alternativo: Describir imágenes para lectores de pantalla
  • Encabezados claros: Utilizar la jerarquía de encabezados adecuada
  • Lenguaje sencillo: Evitar la jerga siempre que sea posible
  • Contraste de código: Asegurarse de que los bloques de código sean legibles

Recursos 📚



📅 Creado hace 1 mes ✏️ Actualizado hace 9 días
glenn-jocher