Menulis docstring

Referensi API LeRobot dibuat langsung dari docstring di src/lerobot/. Docstring bukanlah komentar — ia adalah dokumentasi resmi untuk objek tersebut, dan format di bawah ini adalah yang diparsing oleh renderer dan pemeriksaan CI.

Halaman ini adalah kontrak. Jika Anda menambahkan atau mengedit sesuatu yang publik di src/lerobot/, ikuti kontrak ini.

Metode publik yang tidak terdokumentasi adalah metode yang tidak terlihat. [[autodoc]] secara diam-diam melewati anggota yang tidak memiliki docstring — tanpa peringatan, tanpa error, ia hanya tidak muncul di halaman yang dirender. Cakupan dan kelengkapan referensi API adalah masalah yang sama.

Format dalam satu contoh

Header bagian Google, format tipe Hugging Face. Keduanya, bukan salah satu.

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
        ```
    """

Referensi silang dikecualikan dari contoh di halaman ini — lihat Referensi silang untuk sintaksnya dan mengapa mereka tidak dapat ditampilkan di dalam blok kode.

Aturan

Bagian

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

Dalam urutan tersebut. Tidak ada header bagian lain. Ringkasan satu baris datang terlebih dahulu, kemudian deskripsi bebas opsional, lalu bagian-bagiannya.

Baris Args: diparse oleh mesin

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

Klausul *optional*, defaults to akan diperiksa terhadap nilai default dari signature asli oleh make check-docstrings. Klausul ini bukan sekadar hiasan — jika Anda menulis nilai default yang sudah menyimpang dari kode, CI akan gagal. Hilangkan klausul ini sepenuhnya untuk parameter yang wajib diisi:

    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.

Types go in backticks. Use *optional* with no defaults to when the default is None or is otherwise not worth restating.

Returns: is type-first

Satu baris dengan indentasi, ketik tipe terlebih dahulu, lalu titik dua, lalu deskripsinya:

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

Yields: memiliki bentuk yang sama.

**Atribut**: , tidak pernah Atribut:

doc-builder mengurai Attributes: polos sebagai sinonim dari Parameters:, sehingga atribut Anda dirender sebagai argumen konstruktor. Hal ini terjadi secara diam-diam dan keliru. Setiap kali atribut berbeda dari parameter konstruktor, gunakan bentuk tebal dengan pemisah --:

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.
    """

Catatan --, bukan :.

Referensi silang

Gunakan sintaks kurung siku dari doc-builder: path yang dikutip dengan backtick dan diapit kurung siku. Peran Sphinx (:pymeth:, :pyattr:) tidak didukung dan dirender sebagai teks literal di halaman.

~ menghapus path hanya dari teks tautan; tautan tetap merujuk ke path lengkap.

doc-builder menyelesaikan sintaks ini di mana saja dalam sebuah halaman — termasuk di dalam blok kode berpagar. Itulah mengapa contoh docstring di halaman ini menggunakan teks biasa alih-alih referensi silang: blok kode yang memuatnya akan menampilkan tautan yang telah diselesaikan, bukan sintaks yang perlu Anda ketik. Dalam docstring Anda sendiri, gunakan referensi silang secara bebas; pembatasan ini hanya memengaruhi dokumentasi tentang sintaks tersebut.

Catatan

Gunakan kutipan blok bergaya GitHub:

> [!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.

Komponen <Tip> sudah usang menurut doc-builder; jangan tambahkan yang baru.

Contoh harus diberi pagar

Contoh terdapat di dalam blok ```python yang berisi >>>. Pagar adalah yang membuatnya dirender sebagai blok kode, dan itulah yang dicari oleh regex preprocessor doctest:

    Example:
        ```python
        >>> from lerobot.robots.so_follower import SO101FollowerConfig
        >>> cfg = SO101FollowerConfig(port="/dev/ttyACM0")
        >>> cfg.use_degrees
        True
        ```

>>> yang tidak diberi pagar tetap dikumpulkan — doctest menemukan prompt di mana saja dalam docstring. Yang Anda kehilangan adalah rendering, sehingga tampilannya berupa blok teks panjang di halaman. Setiap contoh membutuhkan pagar.

Setiap contoh dieksekusi di CI atau memiliki # doctest: +SKIP. Apa pun yang menyentuh perangkat keras, GPU, atau mengunduh dari Hub diberi +SKIP:

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

Tambahkan file yang berisi contoh yang dapat dijalankan ke utils/documentation_tests.txt.

Letakkan contoh pada tiga hingga lima titik masuk yang benar-benar ada dalam sebuah modul. Contoh pada accessor yang sepele hanya menjadi kebisingan.

Tiga pola yang akan Anda temui terus-menerus

Dataclass konfigurasi

Bidang konfigurasi secara historis didokumentasikan dengan komentar # di atas setiap bidang. doc-builder tidak dapat melihat komentar inline — kelas seperti itu akan dirender dengan semua bidang tercantum dan tidak ada satu pun deskripsi. Pindahkan mereka ke blok Args: pada docstring kelas:

@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

doc-builder tidak mewarisi docstring dari kelas dasar. Kelas konfigurasi terdaftar LeRobot sering kali berupa shim pewarisan ganda yang tipis:

Disalin

@RobotConfig.register_subclass("so101_follower")
@dataclass
class SOFollowerRobotConfig(RobotConfig, SOFollowerConfig):
    pass

Kelas tersebut merender setiap field — termasuk yang diwarisi — tanpa deskripsi sama sekali, tidak peduli seberapa baik basisnya didokumentasikan. Blok Args: harus berada di kelas konkret yang dinamai oleh [[autodoc]], dan harus mencakup field yang diwarisi juga.

Kelas dasar, kemudian subkelas konkret

Kelas abstrak dasar membawa kontrak kanonik. Subkelas hanya mendokumentasikan apa yang menyimpang — semantik port, keanehan kalibrasi, tata letak motor, kunci fitur yang didukung. Jangan menyalin kontrak dasar ke setiap subkelas.

Robot, Teleoperator, Camera, MotorsBusBase, ProcessorStep, dan PreTrainedPolicy semuanya mengikuti bentuk ini.

Alias tingkat modul

Beberapa nama publik adalah alias, bukan kelas yang berbeda:

SO100FollowerConfig = SOFollowerRobotConfig
SO101FollowerConfig = SOFollowerRobotConfig

[[autodoc]] menyelesaikan alias dan menampilkan nama kelas kanonik, sehingga judul ## SO101FollowerConfig akan menampilkan class lerobot.robots.so_follower.SOFollowerRobotConfig di bagian isi. Dokumentasikan kelas kanonik sekali, dan sebutkan alias-aliasnya dalam teks halaman, bukan dengan memberikan blok autodoc terpisah untuk setiap alias.

Yang tidak perlu didokumentasikan

• Anggota privat. Segala sesuatu yang diawali dengan _ bukan bagian dari API publik.
• Anotasi tipe yang diulang dalam bentuk narasi. port (str): A string. tidak menambah informasi. Jelaskan fungsinya.
• Kode upstream yang di-vendor. src/lerobot/policies/molmoact2/molmoact2_hf_model/ di-vendor dari transformers dan sudah memiliki docstring bergaya upstream. Biarkan apa adanya — merestilainya hanya akan menciptakan konflik pada sinkronisasi berikutnya. Direktori ini dikecualikan dari referensi API dan dari pemeriksaan docstring.

Cara ini diberlakukan

Jalankan keduanya sebelum membuka PR:

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

Lalu render halaman tersebut dan benar-benar lihat hasilnya:

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

Daftar periksa

• Setiap anggota publik yang Anda ubah memiliki docstring.
• Every Args: entry matches the signature, including the *optional*, defaults to clause.
• Returns: adalah type-first pada satu baris yang diindentasi.
• Tidak ada Attributes: polos — gunakan **Attributes**: dengan pemisah --.
• Tidak ada peran Sphinx — referensi silang menggunakan [~module.Class.method].
• Contoh-contoh berada di dalam blok ```python yang dibatasi, dan dijalankan di CI atau memiliki # doctest: +SKIP.
• Field dataclass Config berada di blok Args: pada kelas konkret, bukan komentar #.
• Halaman yang dirender telah diperiksa secara visual.