mirror of
https://github.com/huggingface/lerobot.git
synced 2026-08-08 17:39:44 +00:00
Pepijn
2e8345a5cc
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>
91 lines
3.2 KiB
Markdown
91 lines
3.2 KiB
Markdown
# How to contribute to 🤗 LeRobot
|
|
|
|
Everyone is welcome to contribute, and we value everybody's contribution. Code is not the only way to help the community. Answering questions, helping others, reaching out, and improving the documentation are immensely valuable.
|
|
|
|
Whichever way you choose to contribute, please be mindful to respect our [code of conduct](https://github.com/huggingface/lerobot/blob/main/CODE_OF_CONDUCT.md) and our [AI policy](https://github.com/huggingface/lerobot/blob/main/AI_POLICY.md).
|
|
|
|
## Ways to Contribute
|
|
|
|
You can contribute in many ways:
|
|
|
|
- **Fixing issues:** Resolve bugs or improve existing code.
|
|
- **New features:** Develop new features.
|
|
- **Extend:** Implement new models/policies, robots, or simulation environments and upload datasets to the Hugging Face Hub.
|
|
- **Documentation:** Improve examples, guides, and docstrings.
|
|
- **Feedback:** Submit tickets related to bugs or desired new features.
|
|
|
|
If you are unsure where to start, join our [Discord Channel](https://discord.gg/q8Dzzpym3f).
|
|
|
|
## Development Setup
|
|
|
|
To contribute code, you need to set up a development environment.
|
|
|
|
### 1. Fork and Clone
|
|
|
|
Fork the repository on GitHub, then clone your fork:
|
|
|
|
```bash
|
|
git clone https://github.com/<your-handle>/lerobot.git
|
|
cd lerobot
|
|
git remote add upstream https://github.com/huggingface/lerobot.git
|
|
```
|
|
|
|
### 2. Environment Installation
|
|
|
|
Please follow our [Installation Guide](https://huggingface.co/docs/lerobot/installation) for the environment setup & installation from source.
|
|
|
|
## Running Tests & Quality Checks
|
|
|
|
### Code Style (Pre-commit)
|
|
|
|
Install `pre-commit` hooks to run checks automatically before you commit:
|
|
|
|
```bash
|
|
pre-commit install
|
|
```
|
|
|
|
To run checks manually on all files:
|
|
|
|
```bash
|
|
pre-commit run --all-files
|
|
```
|
|
|
|
### Docstrings
|
|
|
|
The API reference is generated from the docstrings in `src/lerobot/`. If you add or change anything public, follow the [docstring standard](https://huggingface.co/docs/lerobot/writing_docstrings) — the format is parsed by the renderer and checked in CI.
|
|
|
|
### Running Tests
|
|
|
|
We use `pytest`. First, ensure you have test artifacts by installing **git-lfs**:
|
|
|
|
```bash
|
|
git lfs install
|
|
git lfs pull
|
|
```
|
|
|
|
Run the full suite (this may require extras installed):
|
|
|
|
```bash
|
|
pytest -sv ./tests
|
|
```
|
|
|
|
Or run a specific test file during development:
|
|
|
|
```bash
|
|
pytest -sv tests/test_specific_feature.py
|
|
```
|
|
|
|
## Submitting Issues & Pull Requests
|
|
|
|
Use the templates for required fields and examples.
|
|
|
|
- **Issues:** Follow the [ticket template](https://github.com/huggingface/lerobot/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml).
|
|
- **Pull requests:** Rebase on `upstream/main`, use a descriptive branch (don't work on `main`), run `pre-commit` and tests locally, and follow the [PR template](https://github.com/huggingface/lerobot/blob/main/.github/PULL_REQUEST_TEMPLATE.md).
|
|
|
|
> [!IMPORTANT]
|
|
> Community Review Policy: To help scale our efforts and foster a collaborative environment, we ask contributors to review at least one other person's open PR before their own receives attention. This shared responsibility multiplies our review capacity and helps everyone's code get merged faster!
|
|
|
|
Once you have submitted your PR and completed a peer review, a member of the LeRobot team will review your contribution.
|
|
|
|
Thank you for contributing to LeRobot!
|