ドキュメント文字列の作成

LeRobotのAPIリファレンスは、src/lerobot/内のdocstringから直接生成されます。docstringはコメントではなく、そのオブジェクトの公開ドキュメントであり、以下の形式がレンダラーとCIチェックによって解析される形式です。

このページが契約書です。src/lerobot/内のパブリックな要素を追加または編集する場合は、これに従ってください。

ドキュメント化されていない公開メソッドは、存在しないのと同じです。 [[autodoc]] は、docstring がないメンバーを警告やエラーなしに静かにスキップします。そのため、レンダリングされたページに表示されません。カバレッジと API リファレンスの完全性は、同じ問題です。

1つの例の形式

Googleのセクションヘッダー、Hugging Faceのタイプフォーマット。両方です。どちらか一方ではありません。

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

このページの例では、相互参照は省略されています。相互参照の構文と、コードブロック内に表示できない理由については、相互参照を参照してください。

ルール

セクション

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

その順序です。他のセクションヘッダーはありません。まず1行の概要、次に任意の自由形式の説明、最後に各セクションが続きます。

Args: 行は機械によって解析されます

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

*optional*, defaults to 句は、make check-docstrings によって 実際のシグネチャのデフォルト値と照合 されます。装飾的なものではありません。コードから乖離したデフォルト値を記述すると、CI が失敗します。必須のパラメータについては、この句を完全に省略してください。

    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.

型はバッククォートで囲みます。デフォルトがNoneである場合や、改めて述べる価値がない場合は、*optional*のみを使用し、defaults toは付けません。

Returns: 型優先

インデント付きの1行で、最初にタイプ、次にコロン、最後に説明を入力します:

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

Yields: 同一の形状を返します。

**Attributes**: , never 属性:

doc-builder は、単体のAttributes:をParameters:の同義語として解析するため、属性がコンストラクタの引数としてレンダリングされます。これは無言で誤った動作です。属性がコンストラクタの引数と異なる場合は、--区切り付きの太字形式を使用してください。

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

-- であり、: ではありません。

相互参照

doc-builder の括弧構文を使用します: 角括弧で囲まれたバッククォートで引用されたパスです。 Sphinx ロール (:pymeth:、:pyattr:) はサポートされていません。ページ上ではリテラルテキストとして表示されます。

~ は、リンクテキストのみからパスを削除します。リンク自体は引き続きフルパスに解決されます。

doc-builder は、ページ内のあらゆる場所（フェンストコードブロック内を含む）でこの構文を解決します。そのため、このページの docstring の例では、クロスリファレンスではなくプレーンな文章を使用しています。クロスリファレンスを含むコードブロックは、入力すべき構文ではなく、解決されたリンクとしてレンダリングされるためです。ご自身の docstring では、クロスリファレンスを自由に使用してください。この制限は、構文についてのドキュメントにのみ影響します。

コールアウト

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.

<Tip> コンポーネントは doc-builder においてレガシーとされています。新しいものを追加しないでください。

例はフェンスで囲む必要があります

例は、>>> を含む ```python のフェンス付きブロック内にあります。フェンスがあることでコードブロックとしてレンダリングされ、doctestプリプロセッサの正規表現がこれを探します。

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

フェンスなしの>>>も収集されます。doctestはdocstring内のどこにプロンプトがあっても検出します。失われるのはレンダリングであり、ページ上では文章の塊として表示されます。すべての例にはフェンスが必要です。

すべての例はCIで実行されるか、# doctest: +SKIPが付与されています。ハードウェア、GPU、またはHubからのダウンロードに関わるものには+SKIPが付与されます:

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

実行可能な例を含むファイルをutils/documentation_tests.txtに追加します。

モジュールの3〜5つの本質的なエントリポイントに例を配置してください。自明なアクセサーに例を付けるのはノイズになります。

頻繁に遭遇する3つのパターン

Configデータクラス

設定フィールドは、歴史的に各フィールドの上部に#コメントで文書化されてきました。doc-builderはインラインコメントを認識できません — このようなクラスは、すべてのフィールドが列挙され、説明が1つも表示されない形でレンダリングされます。それらをクラスのdocstringのArgs:ブロック内に移動してください:

@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はベースクラスからdocstringを継承しません。LeRobotに登録されている設定クラスは、多くの場合、薄い多重継承のシムです：

コピーしました

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

そのクラスは、ベースクラスのドキュメントがどれだけ充実していても、継承したフィールドを含むすべてのフィールドを、説明なしでレンダリングします。Args:ブロックは、[[autodoc]]が指定する具体的なクラスに記述する必要があり、継承されたフィールドもカバーしなければなりません。

ベースクラス、その後具体的なサブクラス

抽象基底クラスが正規の契約を保持します。サブクラスは、ポートのセマンティクス、キャリブレーションの癖、モーターのレイアウト、サポートされる機能キーなど、基底クラスから逸脱する点のみをドキュメント化してください。基底クラスの契約をすべてのサブクラスにコピーしないでください。

Robot、Teleoperator、Camera、MotorsBusBase、ProcessorStep、PreTrainedPolicyはいずれもこの形状に従います。

モジュールレベルのエイリアス

いくつかのパブリックな名前（公開名）は、個別のクラスではなくエイリアスです。

SO100FollowerConfig = SOFollowerRobotConfig
SO101FollowerConfig = SOFollowerRobotConfig

[[autodoc]]はエイリアスを解決し、正規のクラス名をレンダリングします。そのため、## SO101FollowerConfigという見出しを持つ場合、本文にはclass lerobot.robots.so_follower.SOFollowerRobotConfigが表示されます。正規のクラスは一度だけドキュメント化し、各エイリアスに個別のautodocブロックを割り当てるのではなく、ページの本文でエイリアスに言及してください。

ドキュメントに含めるべきでないこと

• プライベートメンバー。_で始まるものは、パブリックAPIの一部ではありません。
• 散文として再述された型アノテーション。 port (str): A string. は何の役にも立ちません。その用途を述べてください。
• アップストリームからベンダーしたコード。 src/lerobot/policies/molmoact2/molmoact2_hf_model/ は transformers からベンダーされており、すでにアップストリーム形式のドキュメント文字列が付与されています。変更しないでください。スタイルを再設定すると、次の同期時に競合が発生するだけです。API リファレンスおよびドキュメント文字列のチェックから除外されています。

これがどのように強制されるか

PR を作成する前に、これらをまとめて実行してください:

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

次に、ページをレンダリングして、実際に確認します:

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

チェックリスト

• 変更したすべての公開メンバーにドキュメント文字列があります。
• すべてのArgs:エントリはシグネチャと一致しており、*optional*, defaults toの句も含みます。
• Returns: は、1行インデントで型を先頭に置きます。
• 裸のAttributes:は使用しないでください。**Attributes**:に--の区切り文字を使用してください。
• Sphinx ロールは使用しません — クロスリファレンスには [~module.Class.method] を使用します。
• 例は```pythonブロック内にあり、CIで実行されるか、# doctest: +SKIPが付与されています。
• Configデータクラスのフィールドは、具体的なクラス内のArgs:ブロック内に記述されており、#コメントではありません。
• レンダリングされたページを目視で確認しました。