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>
121 lines
3.9 KiB
YAML
121 lines
3.9 KiB
YAML
# Copyright 2024 The HuggingFace Inc. team. All rights reserved.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
default_language_version:
|
|
python: python3.12
|
|
|
|
exclude: "tests/artifacts/.*\\.safetensors$"
|
|
|
|
repos:
|
|
##### Meta #####
|
|
- repo: meta
|
|
hooks:
|
|
- id: check-useless-excludes
|
|
- id: check-hooks-apply
|
|
|
|
##### General Code Quality & Formatting #####
|
|
- repo: https://github.com/pre-commit/pre-commit-hooks
|
|
rev: v6.0.0
|
|
hooks:
|
|
- id: check-added-large-files
|
|
args: ['--maxkb=1024']
|
|
- id: debug-statements
|
|
- id: check-merge-conflict
|
|
- id: check-case-conflict
|
|
- id: check-yaml
|
|
- id: check-toml
|
|
- id: end-of-file-fixer
|
|
- id: trailing-whitespace
|
|
|
|
- repo: https://github.com/astral-sh/ruff-pre-commit
|
|
rev: v0.14.1
|
|
hooks:
|
|
- id: ruff-format
|
|
- id: ruff
|
|
args: [--fix, --exit-non-zero-on-fix]
|
|
|
|
- repo: https://github.com/adhtruong/mirrors-typos
|
|
rev: v1.38.1
|
|
hooks:
|
|
- id: typos
|
|
args: [--force-exclude]
|
|
|
|
- repo: https://github.com/asottile/pyupgrade
|
|
rev: v3.21.0
|
|
hooks:
|
|
- id: pyupgrade
|
|
args: [--py312-plus]
|
|
|
|
##### Markdown Quality #####
|
|
- repo: https://github.com/rbubley/mirrors-prettier
|
|
rev: v3.6.2
|
|
hooks:
|
|
- id: prettier
|
|
name: Format Markdown with Prettier
|
|
types_or: [markdown, mdx]
|
|
args: [--prose-wrap=preserve]
|
|
# Jinja2 model-card templates use a .md extension but contain {% ... %} /
|
|
# {{ ... }} tags that prettier's Markdown formatter mangles (e.g. table loops).
|
|
#
|
|
# docs/source/api/ holds the generated API reference. Its `[[autodoc]]` blocks restrict output
|
|
# to an indented `- member` list, which prettier reads as a lazy paragraph continuation and
|
|
# joins onto one line — silently turning a member list into part of the directive.
|
|
exclude: ^(src/lerobot/templates/.*\.md|docs/source/api/.*\.mdx)$
|
|
|
|
##### Security #####
|
|
- repo: https://github.com/gitleaks/gitleaks
|
|
rev: v8.28.0
|
|
hooks:
|
|
- id: gitleaks
|
|
|
|
- repo: https://github.com/woodruffw/zizmor-pre-commit
|
|
rev: v1.15.2
|
|
hooks:
|
|
- id: zizmor
|
|
|
|
- repo: https://github.com/PyCQA/bandit
|
|
rev: 1.8.6
|
|
hooks:
|
|
- id: bandit
|
|
args: ["-c", "pyproject.toml"]
|
|
additional_dependencies: ["bandit[toml]"]
|
|
|
|
# TODO(Steven): Uncomment when ready to use
|
|
##### Static Analysis & Typing #####
|
|
- repo: https://github.com/pre-commit/mirrors-mypy
|
|
rev: v1.19.1
|
|
hooks:
|
|
- id: mypy
|
|
args: [--config-file=pyproject.toml]
|
|
exclude: ^(examples|benchmarks|tests)/
|
|
|
|
##### Docstring Checks #####
|
|
# - repo: https://github.com/akaihola/darglint2
|
|
# rev: v1.8.2
|
|
# hooks:
|
|
# - id: darglint2
|
|
# args: ["--docstring-style", "google", "-v", "2"]
|
|
# exclude: ^tests/.*$
|
|
|
|
# interrogate runs in CI (quality.yml, doc-checks job) rather than here. Its 1.7.0 release still imports
|
|
# the deprecated `py` package, which resolves against whatever `py` happens to be importable in
|
|
# pre-commit's isolated env — on a machine with miniconda on the path that is a stray `py.py` and the
|
|
# hook dies before it reads any config. The gate is the same either way; the CI step is just reliable.
|
|
# - repo: https://github.com/econchick/interrogate
|
|
# rev: 1.7.0
|
|
# hooks:
|
|
# - id: interrogate
|
|
# args: ["--config=pyproject.toml"]
|
|
# pass_filenames: false
|