mirror of
https://github.com/huggingface/lerobot.git
synced 2026-08-08 17:39:44 +00:00
CarolinePascal
2178e11eaa
Takes src/lerobot/cameras/ to 100% public docstring coverage, the first module of Wave 1 after Person A's robots/ pilot and infrastructure PR. Converts the three config classes that already had prose but used a bold **Attributes**: block (invisible to check_docstrings.py, not the standard's Args: pattern for config dataclasses) and documents the previously-bare CameraConfig, its three enums, ZMQCameraConfig, and the module's utility functions. Adds per-backend sections to docs/source/api/cameras.mdx and removes the module's ruff D-ignore. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
77 lines
4.5 KiB
Markdown
77 lines
4.5 KiB
Markdown
## Title
|
|
|
|
docs(cameras): write the API reference docstrings
|
|
|
|
## Summary / Motivation
|
|
|
|
Continues the docstring-writing initiative Person A started with `docs/robots-api-documentation` (infra +
|
|
`robots/` pilot). This PR takes `src/lerobot/cameras/` to 100% public docstring coverage, chosen first out
|
|
of Wave 1's three hardware modules (`teleoperators`, `motors`, `cameras`) because it had the smallest,
|
|
most concentrated remaining gap — most of `opencv`/`realsense`/`reachy2_camera` were already documented,
|
|
just not in the machine-checkable `Args:` shape the standard requires for config dataclasses.
|
|
|
|
## Related issues
|
|
|
|
- Related: docstring-writing initiative (Wave 1, see `docs/source/writing_docstrings.mdx`)
|
|
|
|
## What changed
|
|
|
|
- `configs.py`: documented the base `CameraConfig` dataclass and its three `Enum`s (`ColorMode`,
|
|
`Cv2Rotation`, `Cv2Backends`).
|
|
- `zmq/configuration_zmq.py`: `ZMQCameraConfig` (previously undocumented) now has a full `Args:` block.
|
|
- `utils.py`: `make_cameras_from_configs` and `get_cv2_rotation` documented, with a runnable `Example:` on
|
|
the former (added to `utils/documentation_tests.txt`).
|
|
- Converted `OpenCVCameraConfig`, `RealSenseCameraConfig`, `Reachy2CameraConfig` from a bold
|
|
`**Attributes**:` field block to `Args:` — the bold form is invisible to `check_docstrings.py`'s parser
|
|
(never fails, just never checked) and doesn't match the standard's dataclass-config pattern. Content
|
|
mostly preserved, reformatted for the type-first / `*optional*, defaults to` shape.
|
|
- Filled the remaining small gaps (dunders, `__post_init__`, a couple of missing class docstrings) in
|
|
`camera_opencv.py`, `camera_realsense.py`, `reachy2_camera.py`, `camera_zmq.py`, `image_server.py`.
|
|
- Added per-backend sections (`OpenCVCamera`, `RealSenseCamera`, `Reachy2Camera`, `ZMQCamera`, plus the
|
|
three enums) to `docs/source/api/cameras.mdx`, mirroring `robots.mdx`'s structure.
|
|
- Removed `"src/lerobot/cameras/**" = ["D"]` from `pyproject.toml`'s ruff ignore list.
|
|
- **Two changes outside the module that cross the stated ownership boundary** (`utils/**` is nominally
|
|
Person A's file, `camera.py` is explicitly "never touch") — both are called out in detail in
|
|
`agents_memory/questions.md`, flagging for A's review:
|
|
- Added `"lerobot.cameras"` to `utils/check_docstrings.py`'s `MODULES_TO_CHECK`. Without it, this PR's
|
|
docstrings are never actually validated against their signatures — the script only checks modules in
|
|
that list, and it only had `"lerobot.robots"`. The script's own docstring calls this "the ratchet: add
|
|
a module here once its docstrings are converted."
|
|
- Fixed 3 pre-existing `D205` violations in `camera.py` (`__enter__`/`__exit__`/`__del__` docstrings
|
|
missing a blank line before the description) — whitespace-only, zero content change, surfaced only
|
|
because removing the module's ruff ignore switched on `D`-rule checking for the whole directory
|
|
including this file.
|
|
- No behavioral changes. No renames, no signature changes.
|
|
|
|
## How was this tested (or how to run locally)
|
|
|
|
```bash
|
|
make check-doctest-list && make check-docstrings && make doctest
|
|
uv run --with interrogate interrogate --config=pyproject.toml
|
|
pre-commit run --all-files
|
|
doc-builder build lerobot docs/source/ --build_dir /tmp/doc-build
|
|
```
|
|
|
|
All pass. Public docstring coverage for `src/lerobot/cameras` measured at 100% (80/80) via the AST script
|
|
from the initiative's tracking process. Rendered `api/cameras.mdx` page eyeballed; all cross-references
|
|
resolve to real anchors (two that would have been dead links — pointing at a property and at a
|
|
non-exported utility class with no autodoc anchor — were rewritten as plain inline code instead, per the
|
|
standard's own guidance on unlinkable targets).
|
|
|
|
## Checklist (required before merge)
|
|
|
|
- [x] Linting/formatting run (`pre-commit run -a`)
|
|
- [x] All tests pass locally (checks above; no test suite changes, docstrings only)
|
|
- [x] Documentation updated (`docs/source/api/cameras.mdx`)
|
|
- [ ] CI is green (pending push)
|
|
- [ ] Community Review
|
|
|
|
## Reviewer notes
|
|
|
|
- `agents_memory/questions.md` lists open items for Person A: the `interrogate` `fail-under` ratchet
|
|
decision, the two ownership-boundary crossings above, `check_config_docstrings.py` being robots-only
|
|
(no equivalent check for `CameraConfig`), and why `opencv`/`realsense`/`reachy2_camera` were already
|
|
partially documented ahead of schedule.
|
|
- Please look closely at the `camera.py` diff (3 lines) and the `check_docstrings.py` diff (1 line) since
|
|
those are the two places this PR touches files outside its nominal ownership.
|