# Автоматические шаблоны docstring и параметров

У каждого [ModularPipelineBlocks](/docs/diffusers/main/ru/api/modular_diffusers/pipeline_blocks#diffusers.ModularPipelineBlocks) есть свойство `doc`, которое автоматически генерируется на основе его `description`, `inputs`, `intermediate_outputs`, `expected_components` и `expected_configs`. Система автоматической генерации docstring поддерживает их синхронизацию с фактическим интерфейсом блока. Шаблоны параметров обеспечивают стандартизированные описания для параметров, которые встречаются во многих конвейерах.

## Автогенерация docstring

Блоки модульного конвейера комбинируются — их можно вложенно размещать, выстраивать в последовательности и свободно переставлять. Их строки документации следуют одному и тому же шаблону. Когда [SequentialPipelineBlocks](/docs/diffusers/main/ru/api/modular_diffusers/pipeline_blocks#diffusers.SequentialPipelineBlocks) агрегирует входные и выходные данные своих подблоков, документация должна обновляться автоматически, без ручного переписывания.

Маркер `# auto_docstring` генерирует строки документации на основе свойств блока. Добавьте его над определением класса, чтобы пометить класс для автоматической генерации строки документации.

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

Выполните следующую команду, чтобы сгенерировать и вставить docstrings.

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

Если у какого-либо помеченного класса отсутствует docstring, проверка завершается ошибкой и выводит список классов, требующих обновления.

```
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` и другие. Полный список доступных имён шаблонов см. в исходном коде.