Docstring yazma

LeRobot API referansı, src/lerobot/ içindeki docstring'lerden doğrudan üretilir. Bir docstring, bir yorum değil, o nesne için yayımlanmış dokümantasyondur ve aşağıdaki biçim, render'ın ve CI kontrollerinin ayrıştırdığı biçimdir.

Bu sayfa sözleşmedir. src/lerobot/ içinde herkese açık herhangi bir şey ekliyorsanız veya düzenliyorsanız, buna uyun.

Belgelenmemiş bir genel yöntem görünmezdir. [[autodoc]], docstring'i olmayan üyeleri sessizce atlar — uyarı veya hata vermez, yalnızca oluşturulan sayfada görünmez. Kapsama ve API referansının tamamlığı aynı sorundur.

Bir örnekteki biçim

Google bölüm başlıkları, Hugging Face tür biçimlendirmesi. İkisi birden, biri ya da diğeri değil.

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

Bu sayfadaki örneklerde çapraz referanslar atlanmıştır — sözdizimleri ve neden bir kod bloğunun içinde gösterilemedikleri hakkında bilgi için Çapraz referanslar bölümüne bakın.

Kurallar

Bölümler

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

Bu sırayla. Başka bölüm başlıkları yok. Önce tek satırlık bir özet gelir, ardından isteğe bağlı serbest biçimli bir açıklama, sonra da bölümler.

Args: satırı makine tarafından ayrıştırılır

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

*optional*, defaults to ifadesi, make check-docstrings tarafından gerçek imza varsayılanıyla karşılaştırılır. Bu ifade süs amaçlı değildir — koddan sapmış bir varsayılan değer yazarsanız CI başarısız olur. Zorunlu parametreler için bu ifadeyi tamamen atlayın:

    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.

Dönüş: tip-önceliklidir

Bir girintili satır, önce tür, ardından iki nokta üst üste, sonra açıklama:

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

Yields: aynı şekle sahiptir.

**Öznitelikler**: , asla Öznitelikler:

doc-builder, çıplak Attributes: ifadesini Parameters: için bir eşanlamlı olarak yorumlar; bu nedenle öznitelikleriniz yapılandırıcı argümanları olarak görüntülenir. Bu durum sessizce gerçekleşir ve yanlıştır. Öznitelikler yapılandırıcı parametrelerinden farklı olduğunda, -- ayıracı içeren kalın biçimi kullanın:

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

Not --, : değil.

Çapraz referanslar

doc-builder’in parantez sözdizimini kullanın: köşeli parantez içinde geri tırnakla alıntılanmış bir yol. Sphinx rolleri (:pymeth:, :pyattr:) desteklenmez ve sayfada düz metin olarak görüntülenir.

~, sadece bağlantı metninden yolu kaldırır; bağlantı yine de tam yola çözümlenir.

doc-builder bu sözdizimini bir sayfadaki her yerde — çitli kod bloklarının içinde dahil olmak üzere — çözümler. Bu nedenle bu sayfadaki docstring örnekleri çapraz referanslar yerine düz metin kullanır: bir çapraz referans içeren kod bloğu, yazmanız gereken sözdizimi yerine çözümlenmiş bağlantıyı görüntüler. Kendi docstring'lerinizde çapraz referansları serbestçe kullanın; bu kısıtlama yalnızca sözdizimi hakkında olan belgeleri etkiler.

Öne Çıkanlar

GitHub tarzı alıntı blokları kullanın:

> [!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> bileşeni, doc-builder'a göre eski usuldür; yeni eklemeyin.

Örnekler çitle çevrilmelidir

Örnek, >>> içeren çitlenmiş bir ```python bloğunun içinde yer alır. Kod bloğu olarak görüntülenmesini sağlayan ve doctest ön işleyicisinin düzenli ifadesinin aradığı şey bu çittir:

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

Çitle çevrilmemiş >>> yine de toplanır — doctest, docstring içinde her yerde prompt'ları bulur. Kaybettiğiniz şey rendering'dir, bu yüzden sayfada bir metin duvarı olarak görünür. Her örneğin çitle çevrilmesi gerekir.

Her örnek ya CI'da çalıştırılır ya da # doctest: +SKIP içerir. Donanım, GPU veya Hub'dan indirme içeren her şey +SKIP alır:

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

Çalıştırılabilir örnekler içeren dosyaları utils/documentation_tests.txt dosyasına ekleyin.

Bir modülün üç ila beş gerçek giriş noktasına örnekler koyun. Trivial erişimcilerdeki örnekler gürültüdür.

Sürekli karşılaşacağınız üç kalıp

Config veri sınıfları

Yapılandırma alanları tarihsel olarak her alanın üzerindeki # yorumlarıyla belgelenmiştir. doc-builder satır içi yorumları göremez — böyle bir sınıf, tüm alanlar listelenmiş ve tek bir açıklama yapılmamış olarak görüntülenir. Bunları sınıf docstring'indeki bir Args: bloğuna taşıyın:

@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, üst sınıflardan docstring miras almaz. LeRobot’ün kayıtlı yapılandırma sınıfları genellikle ince çoklu miras sarmalayıcılarıdır:

Kopyalandı

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

O sınıf, baz sınıflar ne kadar iyi dokümante edilirse edilsin, hiçbir açıklama olmadan tüm alanları — miras alınanlar dahil — çizer. Args: bloğu, [[autodoc]]'in adını verdiği somut sınıfta bulunmalı ve miras alınan alanları da kapsamalıdır.

Taban sınıf, ardından somut alt sınıf

Soyut taban sınıfı, kanonik sözleşmeyi taşır. Alt sınıflar yalnızca sapmaları belgelemelidir — port anlamları, kalibrasyon tuhaflıkları, motor yerleşimi, desteklenen özellik anahtarları. Taban sözleşmesini her alt sınıfa kopyalamayın.

Robot, Teleoperator, Camera, MotorsBusBase, ProcessorStep ve PreTrainedPolicy hepsi bu yapıyı takip eder.

Modül düzeyindeki takma adlar

Birkaç genel ad, ayrı sınıflar yerine takma adlardır:

SO100FollowerConfig = SOFollowerRobotConfig
SO101FollowerConfig = SOFollowerRobotConfig

[[autodoc]] takma adını çözer ve resmi sınıf adını görüntüler; bu nedenle ## SO101FollowerConfig başlığı, gövdede class lerobot.robots.so_follower.SOFollowerRobotConfig olarak görünür. Resmi sınıfı bir kez belgeleyin ve her takma ada kendi autodoc bloğunu vermek yerine, takma adları sayfanın metninde belirtin.

Belgelenmemesi gerekenler

• Özel üyeler. _ ile başlayan her şey genel API'nin bir parçası değildir.
• Proza olarak yeniden ifade edilen tip anotasyonu. port (str): A string. hiçbir şey katmıyor. Ne için kullanıldığını söyleyin.
• Yerel olarak barındırılan (vendored) upstream kodu. src/lerobot/policies/molmoact2/molmoact2_hf_model/ transformers kütüphanesinden yerel olarak barındırılmıştır ve zaten upstream tarzında docstring'ler taşır. Dokunmayın — yeniden biçimlendirmek, bir sonraki senkronizasyonda yalnızca çakışmalara yol açar. API referansından ve docstring kontrollerinden hariç tutulur.

Bunun nasıl uygulandığı

Bir PR açmadan önce bunları birlikte çalıştırın:

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

Sonra sayfayı görüntüleyin ve gerçekten inceleyin:

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

Kontrol listesi

• Dokunduğunuz her herkese açık üyenin bir docstring'i vardır.
• Her Args: girdisi, *optional*, defaults to ifadesi dahil olmak üzere imzayla eşleşir.
• Returns: tek satırda, bir seviye girintili olarak tip önceliği taşır.
• Çıplak Attributes: kullanmayın — -- ayraçlarıyla **Attributes**: kullanın.
• Sphinx rolleri yok — çapraz referanslar [~module.Class.method] kullanılarak yapılır.
• Örnekler, ```python bloğunun içindedir ve ya CI'da çalıştırılır ya da # doctest: +SKIP içerir.
• Config veri sınıfı alanları, somut sınıftaki Args: bloğundadır, # yorumları değildir.
• Render edilen sayfa gözle kontrol edildi.