# Escribir docstrings

La referencia de la API de LeRobot se genera directamente desde las docstrings en `src/lerobot/`. Una docstring no es un comentario: es la documentación publicada para ese objeto, y el formato siguiente es lo que el renderizador y las comprobaciones de CI analizan.

Esta página es el contrato. Si vas a añadir o editar algo público en `src/lerobot/`, síguelo.

> [!IMPORTANT]
> **Un método público sin documentar es invisible.** `[[autodoc]]` omite silenciosamente los miembros que no tienen docstring: no emite ninguna advertencia ni error, simplemente no aparece en la página renderizada. La cobertura y la completitud de la referencia de la API son el mismo problema.

## El formato en un ejemplo

Encabezados de sección de Google, formato de tipo de Hugging Face. Ambos, no uno u otro.

````python
def send_action(self, action: RobotAction, rate_hz: float = 30.0) -> RobotAction:
    """Command the robot to move to a target joint configuration.

    Values are clipped by the configured maximum relative target before reaching the motors, so the
    returned action may differ from the requested one.

    Args:
        action (`dict[str, float]`):
            Target values keyed by motor name, e.g. `{"shoulder_pan.pos": 0.0}`. Keys must match the
            robot's action features.
        rate_hz (`float`, *optional*, defaults to `30.0`):
            Control loop frequency.

    Returns:
        `dict[str, float]`: The action actually written to the motors after safety clipping.

    Raises:
        DeviceNotConnectedError: If the robot has not been connected.

    Example:
        ```python
        >>> from lerobot.robots.so_follower import SO101Follower, SO101FollowerConfig
        >>> robot = SO101Follower(SO101FollowerConfig(port="/dev/ttyACM0"))  # doctest: +SKIP
        >>> robot.connect()  # doctest: +SKIP
        >>> robot.send_action({"shoulder_pan.pos": 0.0})  # doctest: +SKIP
        ```
    """
````

Las referencias cruzadas se omiten en los ejemplos de esta página; consulte [Referencias cruzadas](#cross-references) para conocer su sintaxis y por qué no se pueden mostrar dentro de un bloque de código.

## Reglas

### Secciones

`Args:` · `Returns:` · `Raises:` · `Yields:` · `Example:` · `Note:`

En ese orden. Ningún otro encabezado de sección. Primero va un resumen de una línea, luego una descripción libre opcional y, después, las secciones.

### La línea `Args:` se analiza mediante máquina

```
name (`type`, *optional*, defaults to `X`):
    Description, indented on its own line.
```

La cláusula `*optional*, defaults to` se **compara con el valor predeterminado real de la firma** mediante `make check-docstrings`. No es decorativa: si escribes un valor predeterminado que ha divergido del código, CI falla. Omitir la cláusula por completo para los parámetros obligatorios:

```python
    Args:
        port (`str`):
            Serial port the arm is connected to, e.g. `/dev/ttyACM0`.
        max_relative_target (`float | dict[str, float]`, *optional*):
            Caps the magnitude of the relative positional target vector. `None` disables clipping.
        use_degrees (`bool`, *optional*, defaults to `True`):
            Keep `True` for backward compatibility with existing policies and datasets.
```

Los tipos van entre comillas invertidas. Use `*optional*` sin `defaults to` cuando el valor predeterminado sea `None` o no merezca ser reiterado.

### `Returns:` es de tipo primero

Una línea con sangría, primero el tipo, luego dos puntos y después la descripción:

```python
    Returns:
        `dict[str, float]`: The action actually written to the motors after safety clipping.
```

`Yields:` tiene la misma forma.

### `**Attributes**:`, nunca `Attributes:`

doc-builder interpreta un `Attributes:` sin más como un **sinónimo de `Parameters:`**, por lo que tus atributos se renderizan como argumentos del constructor. Esto es silencioso e incorrecto. Siempre que los atributos difieran de los parámetros del constructor, usa la forma en negrita con un separador `--`:

```python
class Robot(abc.ABC):
    """The base abstract class for all LeRobot-compatible robots.

    **Attributes**:
        - **config_class** (`type[RobotConfig]`) -- The expected configuration class for this robot.
        - **name** (`str`) -- The unique robot name used to identify this robot type.
    """
```

Nota `--`, no `:`.

### Referencias cruzadas

Use la sintaxis de corchetes de doc-builder: una ruta entre corchetes y comillas invertidas. **Los roles de Sphinx (`:pymeth:`, `:pyattr:`) no son compatibles** y se muestran como texto literal en la página.

| Desea                         | Escribir                               |
| ---------------------------- | ----------------------------------- |
| Clase en el paquete principal    | &#91;`Robot`&#93;                   |
| Método, mostrar la ruta completa   | &#91;`Robot.connect`&#93;           |
| Método, mostrar el nombre sin adornos   | &#91;`~Robot.connect`&#93;          |
| Ruta anidada                  | &#91;`~robots.Robot.connect`&#93;   |
| Objeto en otra biblioteca de HF | &#91;`~accelerate.Accelerator`&#93; |

El `~` elimina la ruta solo del **texto del enlace**; el enlace sigue resolviéndose a la ruta completa.

> [!NOTE]
> doc-builder resuelve esta sintaxis en todas partes de una página, incluso dentro de bloques de código delimitados. Por eso, los ejemplos de docstring de esta página usan prosa simple en lugar de referencias cruzadas: un bloque de código que contenga una de estas referencias mostraría el enlace resuelto en lugar de la sintaxis que necesitas escribir. En tus propios docstrings, usa referencias cruzadas libremente; esta restricción solo afecta a la documentación _sobre_ la sintaxis.

### Avisos

Usa citas de bloque estilo GitHub:

```markdown
> [!TIP]
> Call this once at startup — it takes about two seconds.

> [!WARNING]
> Torque is disabled on disconnect. The arm will drop if it is holding a load.
```

El componente `<Tip>` es obsoleto según doc-builder; no agregues nuevos.

### Los ejemplos deben estar delimitados

An example lives inside a fenced `  DOCBUILDER_CODE_7 `python Example:
        ```python
        >>> from lerobot.robots.so_follower import SO101FollowerConfig
        >>> cfg = SO101FollowerConfig(port="/dev/ttyACM0")
        >>> cfg.use_degrees
        True
        ```
````

> [!WARNING]
> An unfenced `>>>` is still collected — doctest finds prompts anywhere in a docstring. What you lose is the
> rendering, so it shows up as a wall of prose on the page. Every example needs the fence.

Every example either executes in CI or carries `# doctest: +SKIP`. Anything that touches hardware, a GPU, or
downloads from the Hub gets `+SKIP`:

````python
    Example:
        ```python
        >>> robot.connect()  # doctest: +SKIP
        >>> policy = ACTPolicy.from_pretrained("lerobot/act_aloha_sim_transfer_cube_human")  # doctest: +SKIP
        ```
````

Agregue archivos que contengan ejemplos ejecutables a `utils/documentation_tests.txt`.

Coloca ejemplos en los tres a cinco puntos de entrada genuinos de un módulo. Los ejemplos en accesores triviales son ruido.

## Tres patrones que encontrarás constantemente

### Dataclasses de configuración

Los campos de configuración se documentan históricamente con comentarios `#` sobre cada campo. **doc-builder no puede ver los comentarios en línea**: una clase así se renderiza con todos los campos listados y sin una sola descripción. Muévelos a un bloque `Args:` en la docstring de la clase:

```python
@dataclass
class SOFollowerConfig:
    """Configuration for SO-family follower arms.

    Args:
        port (`str`):
            Serial port the arm is connected to, e.g. `/dev/ttyACM0`.
        max_relative_target (`float | dict[str, float]`, *optional*):
            Caps the magnitude of the relative positional target vector. A scalar applies to all motors;
            a dict maps motor name to a per-motor cap. `None` disables clipping.
        use_degrees (`bool`, *optional*, defaults to `True`):
            Keep `True` for backward compatibility with existing policies and datasets.
    """

    port: str
    max_relative_target: float | dict[str, float] | None = None
    use_degrees: bool = True
```

> [!IMPORTANT]
> **doc-builder no hereda las docstrings de las clases base.** Las clases de configuración registradas de LeRobot suelen ser shims de herencia múltiple delgados:
>
> ```python
> @RobotConfig.register_subclass("so101_follower")
> @dataclass
> class SOFollowerRobotConfig(RobotConfig, SOFollowerConfig):
>     pass
> ```
>
> Esa clase renderiza **cada** campo, incluidos los que hereda, sin descripciones, sin importar lo bien documentadas que estén las clases base. El bloque `Args:` debe estar en la clase concreta que `[[autodoc]]` nombra, y debe cubrir también los campos heredados.

### Clase base y luego subclase concreta

La base abstracta contiene el contrato canónico. Las subclases documentan solo lo que se desvía: semántica del puerto, peculiaridades de calibración, disposición de los motores y claves de funciones admitidas. No copies el contrato de la base en cada subclase.

`Robot`, `Teleoperator`, `Camera`, `MotorsBusBase`, `ProcessorStep` y `PreTrainedPolicy` siguen todos esta forma.

### Alias a nivel de módulo

Varios nombres públicos son alias en lugar de clases distintas:

```python
SO100FollowerConfig = SOFollowerRobotConfig
SO101FollowerConfig = SOFollowerRobotConfig
```

`[[autodoc]]` resuelve el alias y muestra el nombre de clase **canónico**, por lo que un encabezado `## SO101FollowerConfig` mostrará `class lerobot.robots.so_follower.SOFollowerRobotConfig` en el cuerpo. Documenta la clase canónica una sola vez y menciona los alias en el texto de la página, en lugar de asignar a cada alias su propio bloque de autodoc.

## Qué no documentar

- **Miembros privados.** Todo lo que comience con `_` no forma parte de la API pública.
- **La anotación de tipo reescrita en prosa.** `port (`str`): A string.` no aporta nada. Indique para qué sirve.
- **Código de upstream incluido.** `src/lerobot/policies/molmoact2/molmoact2_hf_model/` se incluye desde `transformers` y ya tiene docstrings con el estilo de upstream. Déjalo como está: restilizarlo solo crea conflictos en la próxima sincronización. Está excluido de la referencia de la API y de las comprobaciones de docstrings.

## Cómo se aplica esto

| Comprobar                     | Lo que detecta                                                                                            |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `make check-docstrings`   | Una entrada `Args:` que no coincide con la firma; un valor predeterminado documentado que ha divergido del real |
| `make doctest`            | Ejemplos que ya no se ejecutan                                                                                |
| `make check-doctest-list` | Entradas obsoletas o no ordenadas en `utils/documentation_tests.txt`                                               |
| `ruff` (reglas `D`)        | Violaciones del estilo de convención de Google                                                                         |
| `interrogate`             | Cobertura de docstrings por debajo del umbral actual                                                     |
| doc-builder               | Una ruta de `[[autodoc]]` que apunta a algo que no existe: esto rompe la compilación de la documentación              |

Ejecútelos juntos antes de abrir una PR:

```bash
make check-docstrings && make doctest && pre-commit run --all-files
```

Luego, renderiza la página y mírala en realidad:

```bash
doc-builder build lerobot docs/source/ --build_dir /tmp/doc-build
```

## Lista de verificación

- [ ] Cada miembro público que modificaste tiene una docstring.
- [ ] Cada entrada de `Args:` coincide con la firma, incluida la cláusula `*optional*, defaults to`.
- [ ] `Returns:` es de tipo primero en una línea con sangría.
- [ ] Sin `Attributes:` sueltos: usa `**Attributes**:` con separadores `--`.
- [ ] Sin roles de Sphinx: las referencias cruzadas usan &#91;`~module.Class.method`&#93;.
- [ ] Los ejemplos están dentro de un bloque ` ```python ` y se ejecutan en CI o llevan `# doctest: +SKIP`.
- [ ] Los campos del dataclass de configuración están en un bloque `Args:` en la clase concreta, no en comentarios `#`.
- [ ] La página renderizada ha sido revisada visualmente.

