Ir al contenido

Flujo de trabajo de la documentación 📚

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

Estructura de la documentación 🗂️

Principales sitios de documentación

Estructura del repositorio

docs/
├── en/              # English docs
│   ├──      # 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: Ir al grano rápidamente
  • Voz activa: "Entrenar el modelo" no "El modelo está entrenado".
  • Ejemplos de código: Muestra código funcional para cada concepto
  • Ayudas visuales: Utiliza imágenes/diagramas cuando sea útil
  • Formato coherente: 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 medios de comunicación

Almacenar en repositorio o utilizar CDN:

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

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

Documentación del edificio 🔨

Desarrollo local

Instalar dependencias:

pip install -e ".[docs]"

Construir y servir localmente:

mkdocs serve

Visite 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 los docstrings. 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 parámetros con tipos
  • Devuelve: Descripción del valor de retorno
  • Ejemplos: Ejemplo de código de trabajo

Añadir nuevas páginas 📄

1. Crear archivo Markdown

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

2. Actualizar navegación

Editar mkdocs.yml:

nav:
    - Home: 
    - Guides:
          - New Guide: guides/new-guide/

3. Redactar contenidos

Siga la guía de estilo e incluya ejemplos.

4. Prueba de construcción

mkdocs serve

5. Presentar RP

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

Traducciones 🌐

Añadir traducciones

  1. Copie la versión English en el directorio de idiomas:
cp docs/en/page/ docs/zh/page/

  1. Traducir contenidos, mantener ejemplos de código en English

  2. Actualización mkdocs.yml enlaces alternativos

Normas 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 English
  • Actualizar las traducciones cuando cambie la versión English

Documentación CI 🤖

CI automáticamente:

  • Elabora documentación sobre cada RP
  • Comprobación de enlaces rotos
  • Valida el formato markdown
  • Despliegue en producción al fusionarse con el principal

Corrección de errores de compilación

Problemas comunes:

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

Buenas prácticas ✅

Organización de contenidos

  • Estructura lógica: Agrupar contenidos relacionados
  • Divulgación progresiva: simple → avanzada
  • Enlaces cruzados: Enlace a páginas relacionadas
  • Optimización de la búsqueda: Utiliza títulos y descripciones claros

Mantenimiento

  • Mantente al día: Actualizar para nuevas funciones
  • Eliminar obsoleto: Eliminar contenido obsoleto
  • Compruebe los enlaces: Corrige los enlaces rotos con regularidad
  • Comentarios de los usuarios: Responder a las preguntas más frecuentes

Accesibilidad

  • Texto Alt: Describe las imágenes para los lectores de pantalla
  • Títulos claros: Utilice una jerarquía de encabezamientos adecuada
  • Lenguaje sencillo: Evite la jerga en la medida de lo posible
  • Contraste del código: Garantizar la legibilidad de los bloques de código

Recursos 📚



Creado hace 6 días ✏️ Actualizado hace 6 días
glenn-jocher