# توليد توثيق الدوال تلقائيًا

يولّد مُزيِّن `@auto_docstring` سلاسل توثيق متسقة لفئات النماذج وطرقها. فهو يستورد أوصاف المعايير القياسية تلقائيًا، لذا عليك توثيق المعايير الجديدة أو المخصصة فقط. عند [إضافة نموذج جديد](./modular_transformers)، تخطَّ الصياغات النمطية وركّز على ما هو جديد.

## @auto_docstring

استورد المُزيّن (decorator) في ملف `modular_model.py` (أو `modeling_model.py` للنماذج الأقدم).

```python
from ...utils import auto_docstring
```

إذا كان نموذجك يرث من نموذج مكتبة أخرى في ملفٍ مُعَدّ، فإن `@auto_docstring` مُطبَّق بالفعل في النموذج الأب. ينسخ `make fix-repo` ذلك إلى الملف المُولَّد `modeling_model.py` نيابةً عنك. طبّق المُزيِّن صراحةً فقط لتخصيص سلوكه (النماذج المستقلة، أو التمهيدات المخصصة، أو الحُجج المُعاد تعريفها).

> [!WARNING]
> عند تجاوز أي مُزيِّن في ملفٍ معياري، شمل **جميع** المُزيِّنات من الدالة أو الفئة الأصلية. إذا تجاوزت بعضها فقط، فلن تظهر البقية في ملف النمذجة المُولَّد.

يقبل المُزيِّن (decorator) الحُجُج الاختيارية التالية:

| الحُجّة | الوصف |
|---|---|
| `custom_intro` | وصف للصف أو الطريقة، يُدرج قبل قسم Args. مطلوب للأصناف التي لا تنتهي بـ [لاحقة معترف بها](#how-it-works) مثل `ForCausalLM` أو `ForTokenClassification`. |
| `custom_args` | نص التوثيق (Docstring) الخاص بالباراميترات المحددة. مفيد عندما تظهر نفس الحجج المخصصة في عدة أماكن داخل ملف النمذجة. |
| `checkpoint` | معرّف نقطة تحقق للنموذج (`"org/my-model"`) يُستخدم لتوليد أمثلة الاستخدام. يتجاوز نقطة التحقق المستنتجة تلقائيًا من فئة الإعداد. عادةً ما يُضبط على فئات الإعداد. |

## الاستخدام

يعتمد عمل `@auto_docstring` على ما تقوم بتزيينه. ففئات النماذج تستخرج توثيق المعاملات من `__init__`، بينما تستخرج فئات الإعدادات من التسميات على مستوى الفئة، وتولّد فئات المعالج تلقائيًا ملخصات من مكوّناتها، وتحصل الدوال مثل `forward` على أنواع الإرجاع وأمثلة الاستخدام.

### فئات النماذج

ضع `@auto_docstring` مباشرةً فوق تعريف الفئة. يستنتج المُزيِّن أوصاف المعاملات من توقيع وطريقة `__init__` ووثيقتها.

```python
from transformers.modeling_utils import PreTrainedModel
from ...utils import auto_docstring

@auto_docstring
class MyAwesomeModel(PreTrainedModel):
    def __init__(self, config, custom_parameter: int = 10, another_custom_arg: str = "default"):
        r"""
        custom_parameter (`int`, *optional*, defaults to 10):
            Description of the custom_parameter for MyAwesomeModel.
        another_custom_arg (`str`, *optional*, defaults to "default"):
            Documentation for another unique argument.
        """
        super().__init__(config)
        self.custom_parameter = custom_parameter
        self.another_custom_arg = another_custom_arg
        # ... rest of your init

    # ... other methods
```

مرّر `custom_intro` و`custom_args` للحصول على مزيد من التحكم. يمكن وضع الحُجج المخصّصة في `custom_args` أو في سطر التوثيق الخاص بـ`__init__`. استخدم `custom_args` عندما تتكرر الحُجج نفسها عبر عدة طرق.

```python
@auto_docstring(
    custom_intro="""This model performs specific synergistic operations.
    It builds upon the standard Transformer architecture with unique modifications.""",
    custom_args="""
    custom_parameter (`type`, *optional*, defaults to `default_value`):
        A concise description for custom_parameter if not defined or overriding the description in `auto_docstring.py`.
    internal_helper_arg (`type`, *optional*, defaults to `default_value`):
        A concise description for internal_helper_arg if not defined or overriding the description in `auto_docstring.py`.
    """
)
class MySpecialModel(PreTrainedModel):
    def __init__(self, config: ConfigType, custom_parameter: "type" = "default_value", internal_helper_arg=None):
        # ...
```

كما يُطبَّق `@auto_docstring` على الفئات التي ترث من [ModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.utils.ModelOutput).

```python
@auto_docstring(
    custom_intro="""
    Custom model outputs with additional fields.
    """
)
@dataclass
class MyModelOutput(ImageClassifierOutput):
    r"""
    loss (`torch.Tensor`, *optional*):
        The loss of the model.
    custom_field (`torch.Tensor` of shape `(batch_size, hidden_size)`, *optional*):
        A custom output field specific to this model.
    """

    # Standard fields (hidden_states, logits, attentions, etc.) are documented automatically when
    # the description matches the standard text. Loss typically varies per model, so document it above.
    loss: Optional[torch.Tensor] = None
    logits: Optional[torch.Tensor] = None
    hidden_states: Optional[tuple[torch.Tensor, ...]] = None
    attentions: Optional[tuple[torch.Tensor, ...]] = None
    # Custom fields need to be documented in the docstring above
    custom_field: Optional[torch.Tensor] = None
```

### فئات الإعداد

ضع `@auto_docstring` مباشرةً فوق فئة فرعية من [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig)، إلى جانب مُزيّن `@strict`. يضيف `@strict` التحقق من الأنواع وقت التشغيل ويحوّل الفئة إلى فئة بيانات مُتحقق منها. معلمات الإعداد هي *تعليقات على مستوى الفئة* (وليس حُجج `__init__`)، ويقرأ `@auto_docstring` هذه التعليقات من جسم الفئة لتوليد التوثيق.

يوفر `ConfigArgs` معايير قياسية مثل `vocab_size` و`hidden_size` و`num_hidden_layers`، لذا لا تحتاج إلى وصف ما لم يختلف السلوك. تُستبعد معايير [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig) الأساسية تلقائيًا. يولّد الحجة `checkpoint` مثال الاستخدام.

```python
from huggingface_hub.dataclasses import strict
from ...configuration_utils import PreTrainedConfig
from ...utils import auto_docstring

@strict
@auto_docstring(checkpoint="org/my-model-checkpoint")
class MyModelConfig(PreTrainedConfig):
    r"""
    custom_param (`int`, *optional*, defaults to 64):
        Description of a parameter specific to this model.
    another_param (`str`, *optional*, defaults to `"gelu"`):
        Description of another model-specific parameter.

    ```python
    from transformers import MyModelConfig, MyModel

    configuration = MyModelConfig()
    model = MyModel(configuration)
    configuration = model.config
    ```
    """

    model_type = "my_model"

    # تُوثَّق المعايير القياسية (vocab_size, hidden_size, إلخ) تلقائيًا من ConfigArgs. vocab_size: int = 32000 hidden_size: int = 768 num_hidden_layers: int = 12 # يجب توثيق المعايير الخاصة بالنموذج في سلسلة توثيق الفئة أعلاه. custom_param: int = 64 another_param: str = "gelu"
```

### Processor classes

Multimodal processors ([ProcessorMixin](/docs/transformers/main/ar/main_classes/processors#transformers.ProcessorMixin) subclasses, `processing_*.py`) always use the bare `@auto_docstring`. The class intro is auto-generated. Document only `__init__` parameters not already covered by `ProcessorArgs` (`image_processor`, `tokenizer`, `chat_template`, and others).

If every parameter is standard, omit the docstring. Decorate `__call__` with `@auto_docstring` too. Its body docstring holds only a `Returns:` section plus any extra model-specific call arguments. `return_tensors` is appended automatically.

```python
from ...processing_utils import ProcessorMixin, ProcessingKwargs, Unpack
from ...utils import auto_docstring

class MyModelProcessorKwargs(ProcessingKwargs, total=False):
    _defaults = {"text_kwargs": {"padding": False}}

@auto_docstring
class MyModelProcessor(ProcessorMixin):
    def __init__(self, image_processor=None, tokenizer=None, custom_param: int = 4, **kwargs):
        r"""
        custom_param (`int`, *optional*, defaults to 4):
            A parameter specific to this processor not covered by the standard ProcessorArgs.
        """
        super().__init__(image_processor, tokenizer)
        self.custom_param = custom_param

    @auto_docstring
    def __call__(self, images=None, text=None, **kwargs: Unpack[MyModelProcessorKwargs]):
        r"""
        Returns:
            [BatchFeature](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.BatchFeature): A [BatchFeature](/docs/transformers/main/ar/main_classes/feature_extractor#transformers.BatchFeature) with the following fields:

            - **input_ids** -- Token ids to be fed to the model.
            - **pixel_values** -- Pixel values to be fed to the model.
        """
        # ...
```

#### معالجات الصور والفيديو

تتبع معالجات الصور والفيديو (فئات فرعية من `BaseImageProcessor`، `image_processing_*.py`) أحد نمطين.

إذا كانت المعالج يحتوي على معاملات خاصة بالنموذج، فعرّف `XxxImageProcessorKwargs(ImagesKwargs, total=False)` TypedDict مع سلسلة توثيق لتلك المعاملات، واضبط `valid_kwargs` على الفئة، واستخدم `@auto_docstring` العاري. لا تحتوي `__init__` على سلسلة توثيق.

```python
class MyModelImageProcessorKwargs(ImagesKwargs, total=False):
    r"""
    custom_threshold (`float`, *optional*, defaults to `self.custom_threshold`):
        A parameter specific to this image processor.
    """
    custom_threshold: float | None

@auto_docstring
class MyModelImageProcessor(TorchvisionBackend):
    valid_kwargs = MyModelImageProcessorKwargs
    custom_threshold: float = 0.5

    def __init__(self, **kwargs: Unpack[MyModelImageProcessorKwargs]):
        super().__init__(**kwargs)
```

إذا كانت الفئة تضبط فقط سمات مستوى الفئة القياسية (`size`، `resample`، `image_mean`، إلخ) دون أي معاملات إضافية مخصصة، فاستخدم `@auto_docstring(custom_intro="Constructs a MyModel image processor.")` بدلاً من ذلك.

```python
@auto_docstring(custom_intro="Constructs a MyModel image processor.")
class MyModelImageProcessor(TorchvisionBackend):
    resample = PILImageResampling.BICUBIC
    image_mean = IMAGENET_STANDARD_MEAN
    image_std = IMAGENET_STANDARD_STD
    size = {"height": 224, "width": 224}
```

عند تجاوز `preprocess`، زُيِّنه بـ `@auto_docstring` ووثِّق فقط الحُجج غير الموجودة في `ImageProcessorArgs`. تُضمَّن الحُجج القياسية و`return_tensors` تلقائيًا.

### الدوال

ضع `@auto_docstring` مباشرةً فوق تعريف الدالة. يستنتج المُزيِّن (decorator) أوصاف المعاملات من توقيع الدالة.

يولّد المُزيِّن نصَّ قيمة الإرجاع من سلسلة التوثيق الخاصة بفئة `ModelOutput`.

```python
class MyModel(PreTrainedModel):
    # ...
    @auto_docstring
    def forward(
        self,
        input_ids: Optional[torch.Tensor] = None,
        attention_mask: Optional[torch.Tensor] = None,
        new_custom_argument: Optional[torch.Tensor] = None,
        # ... other arguments
    ) -> Union[Tuple, ModelOutput]:
        r"""
        new_custom_argument (`torch.Tensor`, *optional*):
            Description of this new custom argument and its expected shape or type.
        """
        # ...
```

مرّر `custom_intro` و`custom_args` للحصول على مزيد من التحكم. استخدم `custom_args` لتعريف توثيق مشترك للحجج مرة واحدة عندما تظهر نفس المعلمات في عدة طرق.

```python
MODEL_COMMON_CUSTOM_ARGS = r"""
    common_arg_1 (`torch.Tensor`, *optional*, defaults to `default_value`):
        Description of common_arg_1
    common_arg_2 (`torch.Tensor`, *optional*, defaults to `default_value`):
        Description of common_arg_2
"""

class MyModel(PreTrainedModel):
    # ...
    @auto_docstring(
        custom_intro="""This is a custom introduction for the function.""",
        custom_args=MODEL_COMMON_CUSTOM_ARGS
    )
    def forward(self, input_ids=None, common_arg_1=None, common_arg_2=None) -> ModelOutput:
        r"""method-specific args go here"""
        # ...
```

اكتب قسمي `Returns` و`Examples` يدويًا في سلسلة التوثيق لتجاوز النسخ المولّدة تلقائيًا.

```python
    def forward(self, input_ids=None) -> torch.Tensor:
        r"""
        Returns:
            `torch.Tensor`: A custom Returns section for non-ModelOutput return types.

        Example:

        ```python
        model = MyModel.from_pretrained("org/my-model")
        output = model(input_ids)
        ```
        """
        # ...
```

### Documenting arguments

Follow these rules when documenting different argument types.

- `auto_docstring.py` defines standard arguments (`input_ids`, `attention_mask`, `pixel_values`, etc.) and includes them automatically. Don't redefine them locally unless the argument behaves differently in your model.

    If a standard argument behaves differently in your model, override it locally in a `r""" """` block. The local definition takes priority. The `labels` argument, for instance, is commonly customized per model and often needs an override.

- Standard config arguments (`vocab_size`, `hidden_size`, `num_hidden_layers`, etc.) follow the same principle but come from `ConfigArgs`. Standard processor arguments (`image_processor`, `tokenizer`, `do_resize`, `return_tensors`, etc.) come from `ProcessorArgs` and `ImageProcessorArgs`. Only document a parameter if it is model-specific or behaves differently from the standard description.

- Document new or custom arguments in an `r""" """` block. Place them after the signature for functions, in the `__init__` docstring for model or processor classes, in the class body docstring for config classes, or in the `XxxImageProcessorKwargs` TypedDict body for image processors.

    ```py
    argument_name (`type`, *optional*, defaults to `X`):
        Description of the argument.
        Explain its purpose, expected shape/type if complex, and default behavior.
        This can span multiple lines.
    ```

  * شمل `type` بين علامتي تنصيص خلفيتين.
  * أضف *اختياري* إذا لم يكن الحُجج مطلوباً أو كان له قيمة افتراضية.
  * أضِف "الافتراضي هو X" إذا كان له قيمة افتراضية. لا حاجة إلى إضافة "الافتراضي هو `None`" إذا كانت القيمة الافتراضية هي `None`.
  * مرّر نفس الكتلة إلى `custom_args` عندما تتكرر نفس الحجج عبر عدة طرق (انظر [مثال الدوال أعلاه](#functions)).

- يستخرج المُزيِّن الأنواع تلقائيًا من توقيعات الدوال. إذا كان للمعامل نوع مُعلَّم، فلا حاجة إلى تكرار النوع في سلسلة تنسيق المستند. عند وجود كلاهما، يكون لنوع التوقيع الأولوية. يعمل نوع المستند كبديل للمعاملات غير المعلَّمة.

## التحقق من نصوص التوثيق

يُتحقق من سلاسل التوثيق (docstrings) عبر سكربت أدوات عند فتح طلب سحب. يقوم CI بتشغيل السكربت والتحقق مما يلي.

> [!TIP]
> إذا ظهر `[ERROR]` في المخرجات، أضف وصف المعامل إلى سلسلة التوثيق أو إلى فئة Args المناسبة في `auto_docstring.py`.

* يتحقق من أن `@auto_docstring` مطبّق على فئات النماذج ذات الصلة والوظائف العامة.
* يتحقق من اكتمال الحُجج واتساقها: يجب أن تكون الحُجج الموثقة موجودة في التوقيع، وأن تتطابق الأنواع والقيم الافتراضية. كما يتم تحديد الحُجج غير المعروفة التي لا تحتوي على وصف محلي.
* يُصدر تحذيرًا عند وجود أماكن مخصصة غير مكتملة مثل `<fill_type>` و`<fill_docstring>`.
* يتحقق من أن التعليقات التوضيحية تتبع نمط التنسيق المتوقع.

نفّذ الفحص محليًا قبل الإرسال.

```bash
make fix-repo
```

`make fix-repo` ينفّذ عدة فحوصات أخرى أيضًا. لتشغيل فحوصات docstring وauto-docstring فقط، استخدم الأمر أدناه.

```bash
# to only check files included in the diff without fixing them
python utils/check_docstrings.py
# to fix and overwrite the files in the diff
# python utils/check_docstrings.py --fix_and_overwrite
# to fix and overwrite all files
# python utils/check_docstrings.py --fix_and_overwrite --check_all
```

## قائمة مرجعية سريعة

| Do | لا |
|---|---|
| طبّق `@auto_docstring` على فئات النموذج والإعداد والمعالج وطرقها الأساسية (`forward`، `__call__`، `preprocess`). | أضف `@auto_docstring` إلى النماذج الموروثة في الملفات المعيارية لأنه يُنقل تلقائيًا. |
| وثّق فقط الحجج الجديدة أو الخاصة بالنموذج. | إعادة تعريف الحُجج القياسية (`input_ids`، `attention_mask`، `vocab_size`، إلخ) التي تتصرف بنفس طريقة أوصافها الافتراضية. |
| ضع معاملات الإعداد في سلسلة توثيق جسم الفئة كملاحظات على مستوى الفئة. | ضع معاملات الإعداد في `__init__`. |
| ضع معالجات الصور في `XxxImageProcessorKwargs` TypedDict. | ضع معالجات الصور في `__init__`. |
| شغّل `python utils/check_docstrings.py --fix_and_overwrite` قبل الإرسال. | تجاهل المخرجات `[ERROR]` لأنها تعني أن المعامل غير موثّق. |

## كيف يعمل

يولّد المُزيِّن `@auto_docstring` سلاسل التوثيق عبر الخطوات التالية.

1. يفحص الزخّار التوقيع لقراءة الحُجج والأنواع والقيم الافتراضية من `__init__` للفئة المزخرفة أو من الدالة المزخرفة. أما لفئات الإعداد، فيتتبع التعليقات على مستوى الفئة عبر سلسلة الوراثة ويتوقف قبل [PreTrainedConfig](/docs/transformers/main/ar/main_classes/configuration#transformers.PreTrainedConfig)، مستثنياً حقول الفئة الأساسية.

    يقوم تلقائيًا بتصفية المعاملات مثل `self` و`kwargs` و`args` و`deprecated_arguments` والأسماء التي تبدأ بـ`_`. كما يتم إعادة تسمية بعض المعاملات الخاصة إلى ما يعادلها من المعاملات العامة (`_out_features` إلى `out_features` في نماذج الهيكل العظمي).

2. تأتي أوصاف الحجج الشائعة من `auto_docstring.py`: `ModelArgs` (مدخلات النموذج)، `ModelOutputArgs` (حقول المخرجات مثل `hidden_states`)، `ImageProcessorArgs` (المعالجة المسبقة للصور)، `ProcessorArgs` (مكونات المعالج متعدد الوسائط)، و`ConfigArgs` (معلمات الإعدادات الفائقة).

3. تتبع وصف كل معامل هذا التسلسل الأولوي:

    - تتمتع سلسلة التوثيق اليدوية (كتلة `r""" """` أو `custom_args`) بالأولوية.
    - يُعدّ قاموس المصدر المُعرَّف مسبقًا (`ModelArgs`، `ModelForArgs`، `ConfigArgs`، `ImageProcessorArgs`، `ProcessorArgs`، `ModelOutputArgs`) هو الخيار الاحتياطي.
    - إذا لم يكن لأيٍّ من المصدرين وصف، يُعلَّم المعامل بـ `[ERROR]` في مخرجات البناء.

4. بالنسبة لفئات النماذج التي تحمل أسماء قياسية مثل `ModelForCausalLM`، أو الفئات التي تُخاط إلى خط أنابيب، يولّد `@auto_docstring` المقدمة. أما بالنسبة لمعالجات الوسائط المتعددة، فتُدرج المقدمة المكونات (مجزّئ النص، ومعالج الصور، وما إلى ذلك) التي تغلفها الفئة. راجع [ClassDocstring](https://github.com/huggingface/transformers/blob/main/src/transformers/utils/auto_docstring.py#L2437) للحصول على القائمة الكاملة.

    إذا لم يكن اسم الفئة موجودًا في `ClassDocstring`، فعيّن `custom_intro`.

5. يمكن أن تشير سلاسل التوثيق (docstrings) المُعرَّفة مسبقًا إلى قيم ديناميكية من [auto_modules](https://github.com/huggingface/transformers/tree/main/src/transformers/models/auto) في Transformers، مثل `{processor_class}` و`{image_processor_class}` و`{config_class}`. يتم حلّ العلامات الوهمية تلقائيًا.

6. يختار المُزيِّن أمثلة الاستخدام بناءً على مهمة النموذج أو توافق خط المعالجة. إنه يقرأ بيانات الوصف (metadata) من نقطة التفتيش من فئة الإعدادات، بحيث تستخدم الأمثلة معرّفات نماذج حقيقية. يتجاوز الحُجّة `checkpoint` نقطة التفتيش المستنتجة من توثيق فئة الإعدادات. اضبط `checkpoint` على فئات الإعدادات، أو عندما يفشل استنتاج نقطة التفتيش. إذا ظهر لك خطأ مثل `"Config not found for <model_name>"`، أضف مدخلاً إلى `HARDCODED_CONFIG_FOR_MODELS` في `auto_docstring.py`.

7. بالنسبة لطرق مثل `forward`، يكتب المُزيّن قسم `Returns` من نوع الإرجاع الخاص بالطريقة. عندما يكون نوع الإرجاع فئة فرعية من [ModelOutput](/docs/transformers/main/ar/main_classes/output#transformers.utils.ModelOutput)، يستخرج `@auto_docstring` أوصاف الحقول من توثيق تلك الفئة. أما كتلة `Returns` مخصصة في توثيق الدالة فتتمتع بالأولوية.

8. بالنسبة للطرق في `UNROLL_KWARGS_METHODS` والفئات في `UNROLL_KWARGS_CLASSES`، يقوم المُزيّن بتوسيع `**kwargs` المُصنّف بـ `Unpack[KwargsTypedDict]`. يصبح كل مفتاح من `TypedDict` معاملًا موثقًا.

    تنطبق التوسعة نفسها على طريقتي `__call__` و`preprocess` في فئات [BaseImageProcessor](/docs/transformers/main/ar/main_classes/image_processor#transformers.BaseImageProcessor) و[ProcessorMixin](/docs/transformers/main/ar/main_classes/processors#transformers.ProcessorMixin) الفرعية. يتم تجاوز الأنواع الأساسية العامة (`TextKwargs`، `ImagesKwargs`، `VideosKwargs`، `AudioKwargs`). يتم فك لفّ الفئات الفرعية الخاصة بالنموذج فقط.