كتابة سلاسل التوثيق

يتم توليد مرجع واجهة برمجة التطبيقات الخاصة بـ LeRobot مباشرةً من سلاسل التوثيق (docstrings) الموجودة في src/lerobot/. سلسلة التوثيق ليست تعليقًا — بل هي التوثيق المنشور لذلك الكائن، والصيغة أدناه هي ما يحلله المُصيِّر (renderer) وفحوصات CI.

هذه الصفحة هي العقد. إذا كنت تضيف أو تعدّل أي شيء عام في src/lerobot/، فالتزم بها.

الطريقة العامة غير الموثقة هي طريقة غير مرئية. يتجاهل [[autodoc]] بصمت الأعضاء الذين لا يملكون نصاً توثيقياً — دون تحذير، ودون خطأ، فهو ببساطة لا يظهر على الصفحة المُصيَّرة. التغطية واكتمال مرجع الواجهة البرمجية هما المشكلة ذاتها.

التنسيق في مثال واحد

عناوين الأقسام الخاصة بـ 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:

بذلك الترتيب. لا تُستخدم عناوين أقسام أخرى. يأتي ملخص من سطر واحد أولاً، ثم وصف حر اختياري، ثم الأقسام.

سطر 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.

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

يعيد: الأولوية لنوع

سطر واحد مُسقط، اكتب النوع أولاً، ثم النقطتين، ثم الوصف:

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

Yields: يأخذ نفس الشكل.

**الخصائص**: , لا

يقوم 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 هذه الصياغة في كل مكان داخل الصفحة — بما في ذلك داخل كتل الأكواد المحاطة. ولهذا السبب تستخدم أمثلة توثيق الدوال (docstrings) في هذه الصفحة نصاً عادياً بدلاً من المراجع المتقاطعة: فكتلة الأكواد التي تحتوي على مرجع متقاطع ستعرض الرابط المُحل بدلاً من الصياغة التي تحتاج إلى كتابتها. في توثيق الدوال الخاص بك، استخدم المراجع المتقاطعة بحرية؛ فقيود هذه الصياغة تؤثر فقط على التوثيق حول الصياغة نفسها.

تنبيهات

استخدم اقتباسات كتل بأسلوب 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 محاطة بأسوار تحتوي على >>>. السور هو ما يجعلها تُعرض ككتلة أكواد، وهو ما يبحث عنه تعبير النمط (regex) في المعالج المسبق لـ doctest:

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

يتم جمع >>> غير المحاط بسياج على أي حال — إذ يجد doctest الأوامر في أي مكان داخل docstring. ما تخسره هو العرض، فيظهر النص كتكتلة من النثر على الصفحة. كل مثال يحتاج إلى السياج.

يُنفَّذ كل مثال في CI أو يحمل # doctest: +SKIP. أي شيء يتعامل مع العتاد، أو وحدة معالجة رسومية، أو يقوم بتنزيلات من 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.

ضع أمثلة على ثلاث إلى خمس نقاط دخول حقيقية للوحدة. الأمثلة على الوصولات البسيطة ضجيج.

ثلاثة أنماط ستواجهها باستمرار

فئات بيانات الإعداد

تُوثَّق حقول الإعداد تاريخياً بتعليقات # فوق كل حقل. لا يمكن لـ doc-builder رؤية التعليقات المضمنة — فتُعرض هذه الفئة مع كل الحقول المذكورة دون أي وصف. انقلها إلى كتلة 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 سلاسل التوثيق (docstrings) من الفئات الأساسية. غالبًا ما تكون فئات الإعداد المسجلة في LeRobot مجرد واجهات رقيقة (shims) تعتمد على الوراثة المتعددة:

تم النسخ

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

ترسم تلك الفئة كل الحقول — بما في ذلك الحقول الموروثة — دون أي أوصاف على الإطلاق، بغضّ النظر عن جودة توثيق الفئات الأساسية. يجب أن يكون كتلة Args: موجودة في الفئة الملموسة التي يسمّيها [[autodoc]]، ويجب أن تغطي الحقول الموروثة أيضاً.

الفئة الأساسية، ثم الفئة الفرعية الملموسة

تحمل الفئة الأساسية المجردة العقد القياسي. توثّق الفئات الفرعية فقط ما ينحرف عن ذلك — دلالات المنفذ، خصوصيات المعايرة، تخطيط المحرك، مفاتيح الميزات المدعومة. لا تنسخ العقد الأساسي إلى كل فئة فرعية.

يتبع Robot وTeleoperator وCamera وMotorsBusBase وProcessorStep وPreTrainedPolicy جميعها هذا الشكل.

مستويات التخصيص على مستوى الوحدة

تعدّ بعض الأسماء العامة مستعارة (aliases) وليست فئات منفصلة:

SO100FollowerConfig = SOFollowerRobotConfig
SO101FollowerConfig = SOFollowerRobotConfig

يحلّ [[autodoc]] الاسم المستعار ويعرض اسم الفئة القياسي، لذا فإن عنوان ## SO101FollowerConfig سيظهر class lerobot.robots.so_follower.SOFollowerRobotConfig في المتن. وثّق الفئة القياسية مرة واحدة، وأشر إلى الأسماء المستعارة في نص الصفحة بدلاً من منح كل اسم مستعار كتلة autodoc خاصة به.

ما لا يجب توثيقه

• أعضاء خاصة. أي شيء يبدأ بـ _ لا يُعد جزءًا من واجهة البرمجة العامة.
• The type annotation restated as prose. port (str): A string. adds nothing. Say what it is for.
• كود مُستورد من المصدر الأصلي. src/lerobot/policies/molmoact2/molmoact2_hf_model/ مُستورد من transformers ويحمل بالفعل توثيقات بأسلوب المصدر الأصلي. اتركه كما هو — فإعادة تنسيقه ستُحدث فقط تعارضات عند المزامنة التالية. وهو مستثنى من مرجع الواجهة البرمجية ومن فحوصات التوثيقات.

كيف يتم فرض ذلك

شغّلها معًا قبل فتح طلب دمج:

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

ثم اعرض الصفحة وانظر إليها فعليًا:

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

قائمة التحقق

• كل عضو عام قمت بتعديله يحتوي على سلسلة توثيق.
• Every Args: entry matches the signature, including the *optional*, defaults to clause.
• Returns: يبدأ النوع في أول سطر مع مسافة بادئة واحدة.
• لا تُستخدم Attributes: بشكل منفرد — استخدم **Attributes**: مع فواصل --.
• لا توجد أدوار Sphinx — تستخدم المراجع المتقاطعة [~module.Class.method].
• توجد الأمثلة داخل كتلة ```python محاطة بعلامات، وتُنفَّذ إما في CI أو تحمل # doctest: +SKIP.
• حقول فئة البيانات Config موجودة في كتلة Args: داخل الفئة الملموسة، وليس في تعليقات #.
• تم فحص الصفحة المُصيَّرة بالعين.