# قوالب التوثيق التلقائي والمعاملات

يحتوي كل [ModularPipelineBlocks](/docs/diffusers/main/ar/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks) على خاصية `doc` يتم توليدها تلقائيًا من `description` و`inputs` و`intermediate_outputs` و`expected_components` و`expected_configs`. يحافظ نظام توثيق الدوال التلقائي على مزامنة توثيق الدوال مع الواجهة الفعلية للكتلة. توفر قوالب المعلمات أوصافًا موحدة للمعلمات التي تظهر عبر خطوط أنابيب متعددة.

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

كتل خط الأنابيب المعيارية قابلة للتركيب — يمكنك تضمينها، وتوصيلها في تسلسلات، وإعادة ترتيبها بحرية. تتبع سطور التوثيق الخاصة بها نفس النمط. عندما تجمع [SequentialPipelineBlocks](/docs/diffusers/main/ar/api/modular_diffusers/pipeline_blocks#diffusers.SequentialPipelineBlocks) المدخلات والمخرجات من كتلها الفرعية، يجب أن يتم تحديث التوثيق تلقائيًا دون الحاجة إلى إعادة كتابة يدوية.

يولّد المؤشر `# auto_docstring` سطور التوثيق من خصائص الكتلة. أضِفه فوق تعريف الفئة لتحديد الفئة لتوليد سطور التوثيق تلقائيًا.

```py
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    ...
```

شغّل الأمر التالي لتوليد سلاسل التوثيق وإدراجها.

```bash
python utils/modular_auto_docstring.py --fix_and_overwrite
```

تقرأ الأداة خاصية `doc` للكتلة وتدرجها كسلسلة توثيق للفئة.

```py
# auto_docstring
class FluxTextEncoderStep(SequentialPipelineBlocks):
    """
    Text input processing step that standardizes text embeddings for the pipeline.

    Inputs:
        prompt_embeds (`torch.Tensor`) *required*:
            text embeddings used to guide the image generation.
        ...

    Outputs:
        prompt_embeds (`torch.Tensor`):
            text embeddings used to guide the image generation.
        ...
    """
```

يمكنك أيضًا التحقق دون الكتابة فوق الملفات، أو استهداف ملف أو مجلد محدد.

```bash
# Check that all marked classes have up-to-date docstrings
python utils/modular_auto_docstring.py

# Check a specific file or directory
python utils/modular_auto_docstring.py src/diffusers/modular_pipelines/flux/
```

إذا كان أي من الفئات المحددة يفتقر إلى سلسلة توثيق، فإن الفحص يفشل ويقوم بإدراج الفئات التي تحتاج إلى تحديث.

```
Found the following # auto_docstring markers that need docstrings:
- src/diffusers/modular_pipelines/flux/encoders.py: FluxTextEncoderStep at line 42

Run `python utils/modular_auto_docstring.py --fix_and_overwrite` to fix them.
```

## قوالب المعلمات

`InputParam` و`OutputParam` تعرّف مدخلات ومخرجات الكتلة. أنشئها مباشرةً أو استخدم `.template()` لتعريفات قياسية للمعاملات الشائعة مثل `prompt` و`num_inference_steps` أو `latents`.

### InputParam

`InputParam` يصف مدخلًا واحدًا إلى كتلة.

| الحقل | النوع | الوصف |
|---|---|---|
| `name` | `str` | اسم المعامل |
| `type_hint` | `Any` | تصنيف النوع (على سبيل المثال، `str`، `torch.Tensor`) |
| `default` | `Any` | القيمة الافتراضية (إذا لم يتم تعيينها، فلا يوجد للباراميتر قيمة افتراضية) |
| `required` | `bool` | ما إذا كان المعامل مطلوباً |
| `description` | `str` | وصف قابل للقراءة من قِبل الإنسان |
| `kwargs_type` | `str` | اسم المجموعة للمعاملات ذات الصلة (مثل `"denoiser_input_fields"`) |
| `metadata` | `dict` | معلومات إضافية اختيارية |

#### إنشاء InputParam مباشرة

```py
from diffusers.modular_pipelines import InputParam

InputParam(
    name="guidance_scale",
    type_hint=float,
    default=7.5,
    description="Scale for classifier-free guidance.",
)
```

#### استخدام قالب

```py
InputParam.template("prompt")
# Equivalent to:
# InputParam(name="prompt", type_hint=str, required=True,
#            description="The prompt or prompts to guide image generation.")
```

تُعيّن القوالب `name` و`type_hint` و`default` و`required` و`description` تلقائياً. يمكنك تجاوز أي حقل أو إضافة سياق باستخدام معامل `note`.

```py
# Override the default value
InputParam.template("num_inference_steps", default=28)

# Add a note to the description
InputParam.template("prompt_embeds", note="batch-expanded")
# description becomes: "text embeddings used to guide the image generation. ... (batch-expanded)"
```

### OutputParam

`OutputParam` يصف مخرَجًا واحدًا من كتلة.

| الحقل | النوع | الوصف |
|---|---|---|
| `name` | `str` | اسم المعامل |
| `type_hint` | `Any` | تعريف النوع |
| `description` | `str` | وصف قابل للقراءة من قِبل الإنسان |
| `kwargs_type` | `str` | اسم المجموعة للمعاملات ذات الصلة |
| `metadata` | `dict` | معلومات إضافية اختيارية |

#### إنشاء OutputParam مباشرة

```py
from diffusers.modular_pipelines import OutputParam

OutputParam(name="image_latents", type_hint=torch.Tensor, description="Encoded image latents.")
```

#### استخدام قالب

```py
OutputParam.template("latents")

# Add a note to the description
OutputParam.template("prompt_embeds", note="batch-expanded")
```

## القوالب المتاحة

`INPUT_PARAM_TEMPLATES` و`OUTPUT_PARAM_TEMPLATES` معرّفة في [modular_pipeline_utils.py](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/modular_pipeline_utils.py). تتضمن هذه القوالب معلمات شائعة مثل `prompt` و`image` و`num_inference_steps` و`latents` و`prompt_embeds` وغيرها. راجع المصدر للحصول على القائمة الكاملة لأسماء القوالب المتاحة.