lerobot

admin/lerobot

Fork 0

mirror of https://github.com/huggingface/lerobot.git synced 2026-08-08 17:39:44 +00:00

Commit Graph

Author	SHA1	Message	Date
CarolinePascal	7daf8f852d	docs(optim): write the API reference docstrings Starts Wave 2. Takes src/lerobot/optim/ to 100% public docstring coverage. Fixes dataclass Args: field order to match the real generated __init__ signature (base-class fields keep their position even when redeclared by a subclass). Adds docs/source/api/optim.mdx, which didn't exist before — needs a _toctree.yml entry from whoever owns that file, see PR description. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-07 10:23:22 +02:00
Pepijn	741005d719	docs: write the API reference docstrings Every docstring change for the API reference, on top of the infrastructure PR which contains none. Two halves: a repo-wide pass over what the renderer cannot handle, and `src/lerobot/robots/` taken to 100% as the worked example. Renderer fixes, repo-wide. Both of these render incorrectly the moment `[[autodoc]]` is on, and both were verified against a local build: - 24 Sphinx roles across three files. They are unsupported and render as literal `:pymeth:` text. Method references become doc-builder cross-references; the ones pointing at instance attributes become inline code, since attributes get no autodoc anchor and a cross-reference would be a dead link. - 43 `Attributes:` sections across 27 files. doc-builder parses a bare `Attributes:` as a synonym for `Parameters:` — `Robot`'s attributes rendered inside `<paramsdesc>`, presenting `config_class` and `name` to readers as constructor arguments when the actual parameter is `config`. Where the original carried no type, the type comes from the real class annotation rather than being invented. The four base classes every other module inherits from — `robot.py`, `teleoperator.py`, `motors_bus.py`, `camera.py` — are rewritten to the standard, since subclasses document only their deviations from that text. Three docstring errors corrected in passing: `Teleoperator.get_action` pointed at `observation_features`, which `Teleoperator` does not have; `send_feedback` documented a `Returns:` for a method returning `None`; and `config_class` was typed `RobotConfig` instead of `type[TeleoperatorConfig]`. `robots/`, 109/306 -> 306/306. The configuration dataclasses were the substantial part. Their fields were documented only with `#` comments above each field, which doc-builder cannot see: before this, `SO101FollowerConfig` rendered all eleven of its fields with not one description. Each config now carries an `Args:` block on the concrete registered class, covering inherited fields too, because doc-builder renders only a class's own docstring and several of these configs are thin multiple-inheritance shims whose body is `pass`. The inline comments are kept rather than removed, so fields stay annotated in the source as well as on the rendered page. Note this leaves each field described twice, and only the `Args:` block is checked against the signature by `make check-docstrings`, so the two can drift. Writing them turned up things worth stating plainly on the page rather than leaving in a comment: which configs have no serial port at all because they talk over a network or the cloud (Reachy 2, Unitree G1, LeKiwi's client, EarthRover), which manage their own calibration so `calibration_dir` does nothing, that OpenArm's default joint limits are deliberately tiny until `side` is set, and that reBot's `port` means a different thing depending on `can_adapter`. Two pre-existing docstring bugs that the doctest infrastructure surfaced are fixed here: `SerialMotorsBus` used `>>>` inside a ```bash block to show CLI output, which doctest read as Python and failed on with a SyntaxError, and `MotorsBus.torque_disabled`'s example referenced an undefined name. `ensure_safe_goal_position` gains a genuinely executing example so the doctest gate is not vacuous. Gates ratcheted, each of which the infrastructure PR left deliberately loose: - `check_docstrings.py`'s ignore list emptied — the ten objects it held all had bare `Attributes:` sections, now converted. - `check_config_docstrings.py`'s ignore list emptied — every registered robot config documents its port and calibration semantics. - `robots/` removed from the ruff `D` per-file-ignores, as are the two package-root files, whose one-line docstring issues are fixed here. D100 and D104 are ignored globally instead: they ask for a banner on every file and every `__init__.py`, which appears on no rendered page. - `interrogate` raised 52 -> 55 against a measured 55.3%. - The four `robots/` files carrying examples added to the doctest allowlist, which shipped empty. Verified: all 66 changed files under `src/lerobot/` are provably docstring-only (AST with docstrings stripped is byte-identical to main), no comment line is removed anywhere in `robots/`, and 708 tests pass. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-08-06 21:01:34 +02:00
Pepijn	2e8345a5cc	docs: add API documentation infrastructure LeRobot's documentation build passes `--not_python_module`, which tells doc-builder there is no importable Python package and disables `[[autodoc]]` entirely. The result is that all 90+ pages are hand-written guides and there is no generated API reference at all. This is the machinery to change that. It deliberately contains no docstring changes of its own — every docstring edit lives in the follow-up PR, so this one can be reviewed as tooling and configuration alone. The standard. `docs/source/writing_docstrings.mdx` is the contract: Google section headers with Hugging Face type formatting, the machine-checked argument line, `Attributes:`, doc-builder cross-references, fenced doctest examples. It also records three behaviours that are not discoverable from the source and were verified against a local build: `[[autodoc]]` silently skips members with no docstring; doc-builder does not inherit docstrings from base classes, so a registered config shim whose body is `pass` renders every field with no description; and module-level aliases resolve to the canonical class. Autodoc turned on, with two changes that are not obvious: - `--version main` on the main-docs job. Without `--not_python_module`, doc-builder resolves the version from `lerobot.__version__` and only maps it to the default branch when it contains "dev". transformers relies on that; our main carries 0.6.2. Verified by building both ways — dropping the flag alone would publish the main docs to /lerobot/v0.6.2/ instead of /lerobot/main/ and disable notebook building. - `pre_command` on both jobs. doc-builder ships a mock-deps registry entry for lerobot, so the reusable workflow takes its light-install path, which cannot import the package. The heavy dependencies cannot be mocked either: draccus runs `register_subclass` at import time and `processor/converters.py` calls `functools.singledispatch.register(torch.Tensor)`, which needs a real class. `[dataset]` is the only extra required. Workflow triggers gain `src/`, since the reference is now generated from docstrings. `docs/source/api/` is excluded from the prettier hook, which reads `[[autodoc]]` member lists as lazy paragraph continuations and joins a ten-entry list onto one line. Nine API reference pages, scaffolded with each module's base class. Doctests. `LeRobotDocTestParser` is mandatory rather than optional here: ruff's `docstring-code-format = true` drops the blank line before a closing fence, after which stdlib's `_EXAMPLE_RE` reads the fence as expected output and every example with output fails. It is written against the installed pytest rather than copied from transformers, whose version predates pytest 9's `import_path` signature and its own fix for the `@property` line-number bug. `preprocess_string` also diverges: the upstream fenced-block split puts a single-line example's code in a chunk with no `>>>` in it, so neither the CUDA skip nor the `+IGNORE_RESULT` injection fires for it. Checkers. `utils/check_docstrings.py` is the ~300-line core of the 2203-line transformers original; the `@auto_docstring` system, modular propagation, GitPython and `checkers.py` are not ported. `utils/check_config_docstrings.py` checks that every registered robot config documents its port and calibration semantics. Gates**, all set to values that pass today: ruff `D` with per-file-ignores per unconverted module, `interrogate` at `fail-under = 52` against a measured 52.1%, and Makefile targets wired into the quality workflow. The doctest allowlist ships empty and the `doctest` target handles that, because the files carrying runnable examples arrive with the docstring PR. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-08-06 20:57:26 +02:00

Author

SHA1

Message

Date

CarolinePascal

7daf8f852d

docs(optim): write the API reference docstrings

Starts Wave 2. Takes src/lerobot/optim/ to 100% public docstring coverage. Fixes dataclass Args: field
order to match the real generated __init__ signature (base-class fields keep their position even when
redeclared by a subclass). Adds docs/source/api/optim.mdx, which didn't exist before — needs a
_toctree.yml entry from whoever owns that file, see PR description.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-08-07 10:23:22 +02:00

Pepijn

741005d719

docs: write the API reference docstrings

Every docstring change for the API reference, on top of the infrastructure PR
which contains none. Two halves: a repo-wide pass over what the renderer cannot
handle, and `src/lerobot/robots/` taken to 100% as the worked example.

**Renderer fixes, repo-wide.** Both of these render incorrectly the moment
`[[autodoc]]` is on, and both were verified against a local build:

- 24 Sphinx roles across three files. They are unsupported and render as literal
  `:pymeth:` text. Method references become doc-builder cross-references; the
  ones pointing at instance attributes become inline code, since attributes get
  no autodoc anchor and a cross-reference would be a dead link.
- 43 `Attributes:` sections across 27 files. doc-builder parses a bare
  `Attributes:` as a synonym for `Parameters:` — `Robot`'s attributes rendered
  inside `<paramsdesc>`, presenting `config_class` and `name` to readers as
  constructor arguments when the actual parameter is `config`. Where the
  original carried no type, the type comes from the real class annotation rather
  than being invented.

The four base classes every other module inherits from — `robot.py`,
`teleoperator.py`, `motors_bus.py`, `camera.py` — are rewritten to the standard,
since subclasses document only their deviations from that text.

Three docstring errors corrected in passing: `Teleoperator.get_action` pointed
at `observation_features`, which `Teleoperator` does not have; `send_feedback`
documented a `Returns:` for a method returning `None`; and `config_class` was
typed `RobotConfig` instead of `type[TeleoperatorConfig]`.

**`robots/`, 109/306 -> 306/306.** The configuration dataclasses were the
substantial part. Their fields were documented only with `#` comments above each
field, which doc-builder cannot see: before this, `SO101FollowerConfig` rendered
all eleven of its fields with not one description. Each config now carries an
`Args:` block on the concrete registered class, covering inherited fields too,
because doc-builder renders only a class's own docstring and several of these
configs are thin multiple-inheritance shims whose body is `pass`.

The inline comments are kept rather than removed, so fields stay annotated in
the source as well as on the rendered page. Note this leaves each field
described twice, and only the `Args:` block is checked against the signature by
`make check-docstrings`, so the two can drift.

Writing them turned up things worth stating plainly on the page rather than
leaving in a comment: which configs have no serial port at all because they talk
over a network or the cloud (Reachy 2, Unitree G1, LeKiwi's client, EarthRover),
which manage their own calibration so `calibration_dir` does nothing, that
OpenArm's default joint limits are deliberately tiny until `side` is set, and
that reBot's `port` means a different thing depending on `can_adapter`.

Two pre-existing docstring bugs that the doctest infrastructure surfaced are
fixed here: `SerialMotorsBus` used `>>>` inside a ```bash block to show CLI
output, which doctest read as Python and failed on with a SyntaxError, and
`MotorsBus.torque_disabled`'s example referenced an undefined name.
`ensure_safe_goal_position` gains a genuinely executing example so the doctest
gate is not vacuous.

**Gates ratcheted**, each of which the infrastructure PR left deliberately
loose:

- `check_docstrings.py`'s ignore list emptied — the ten objects it held all had
  bare `Attributes:` sections, now converted.
- `check_config_docstrings.py`'s ignore list emptied — every registered robot
  config documents its port and calibration semantics.
- `robots/` removed from the ruff `D` per-file-ignores, as are the two
  package-root files, whose one-line docstring issues are fixed here. D100 and
  D104 are ignored globally instead: they ask for a banner on every file and
  every `__init__.py`, which appears on no rendered page.
- `interrogate` raised 52 -> 55 against a measured 55.3%.
- The four `robots/` files carrying examples added to the doctest allowlist,
  which shipped empty.

Verified: all 66 changed files under `src/lerobot/` are provably docstring-only
(AST with docstrings stripped is byte-identical to main), no comment line is
removed anywhere in `robots/`, and 708 tests pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-06 21:01:34 +02:00

Pepijn

2e8345a5cc

docs: add API documentation infrastructure

LeRobot's documentation build passes `--not_python_module`, which tells
doc-builder there is no importable Python package and disables `[[autodoc]]`
entirely. The result is that all 90+ pages are hand-written guides and there is
no generated API reference at all.

This is the machinery to change that. It deliberately contains no docstring
changes of its own — every docstring edit lives in the follow-up PR, so this
one can be reviewed as tooling and configuration alone.

**The standard.** `docs/source/writing_docstrings.mdx` is the contract: Google
section headers with Hugging Face type formatting, the machine-checked argument
line, `**Attributes**:`, doc-builder cross-references, fenced doctest examples.
It also records three behaviours that are not discoverable from the source and
were verified against a local build: `[[autodoc]]` silently skips members with
no docstring; doc-builder does not inherit docstrings from base classes, so a
registered config shim whose body is `pass` renders every field with no
description; and module-level aliases resolve to the canonical class.

**Autodoc turned on**, with two changes that are not obvious:

- `--version main` on the main-docs job. Without `--not_python_module`,
  doc-builder resolves the version from `lerobot.__version__` and only maps it
  to the default branch when it contains "dev". transformers relies on that;
  our main carries 0.6.2. Verified by building both ways — dropping the flag
  alone would publish the main docs to /lerobot/v0.6.2/ instead of
  /lerobot/main/ and disable notebook building.
- `pre_command` on both jobs. doc-builder ships a mock-deps registry entry for
  lerobot, so the reusable workflow takes its light-install path, which cannot
  import the package. The heavy dependencies cannot be mocked either: draccus
  runs `register_subclass` at import time and `processor/converters.py` calls
  `functools.singledispatch.register(torch.Tensor)`, which needs a real class.
  `[dataset]` is the only extra required.

Workflow triggers gain `src/**`, since the reference is now generated from
docstrings. `docs/source/api/` is excluded from the prettier hook, which reads
`[[autodoc]]` member lists as lazy paragraph continuations and joins a ten-entry
list onto one line.

Nine API reference pages, scaffolded with each module's base class.

**Doctests.** `LeRobotDocTestParser` is mandatory rather than optional here:
ruff's `docstring-code-format = true` drops the blank line before a closing
fence, after which stdlib's `_EXAMPLE_RE` reads the fence as expected output and
every example with output fails. It is written against the installed pytest
rather than copied from transformers, whose version predates pytest 9's
`import_path` signature and its own fix for the `@property` line-number bug.
`preprocess_string` also diverges: the upstream fenced-block split puts a
single-line example's code in a chunk with no `>>>` in it, so neither the CUDA
skip nor the `+IGNORE_RESULT` injection fires for it.

**Checkers.** `utils/check_docstrings.py` is the ~300-line core of the
2203-line transformers original; the `@auto_docstring` system, modular
propagation, GitPython and `checkers.py` are not ported.
`utils/check_config_docstrings.py` checks that every registered robot config
documents its port and calibration semantics.

**Gates**, all set to values that pass today: ruff `D` with per-file-ignores
per unconverted module, `interrogate` at `fail-under = 52` against a measured
52.1%, and Makefile targets wired into the quality workflow. The doctest
allowlist ships empty and the `doctest` target handles that, because the files
carrying runnable examples arrive with the docstring PR.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-06 20:57:26 +02:00

3 Commits