Skip to content

# Документация проекта: настройка MkDocs и добавление документации Компонента UI "alert_component.py"

## 1 Структура проекта

    nms_tests/
    ├── docs/
    │ ├── components/
    │ │ └── alert_component.md
    │ └── index.md
    ├
    ├── components/
    │ └── alert_component.py
    └── mkdocs.yml

## 2 Инструкция по настройке MkDocs

### 2.1 Установка зависимостей

powershell pip install mkdocs mkdocs-material mkdocstrings mkdocstrings-python

### 2.2 Инициализация проекта

powershell mkdocs new .

## 3 Добавление документации

### 3.1 Добавление комментариев docstrings в Компонент Alert (alert_component.py)

    python
    """Модуль для работы с компонентом alert-окна в Playwright.

    Содержит класс AlertComponent для взаимодействия с различными типами
    alert-окон (error, success, info, warning) и проверки их состояния.
    """

    from playwright.sync_api import Page, expect
    from tools.logger import get_logger
    from elements.text_element import Text
    from components.base_component import BaseComponent

    logger = get_logger("ALERT")

    class AlertComponent(BaseComponent):
        """Компонент для работы с alert-окнами Playwright.

        Поддерживает типы: error, success, info, warning.
        Позволяет проверять наличие, отсутствие и текст сообщений.
        """

        # ... (полный код класса из исходного файла)

### 3.2 Конфигурация MkDocs (mkdocs.yml)

    yaml
    site_name: Документация тестов
    theme:
      name: material

    plugins:
      - search
      - mkdocstrings:
          default_handler: python
          handlers:
            python:
              paths: [".", "pages"]
              options:
                show_source: true

    nav:
      - Главная: index.md
      - Компоненты UI:
        - AlertComponent: components/alert_component.md
      # ... (остальная структура навигации)

### 3.3 Создание файла описания Компонента Alert

docs/components/alert_component.md:

    markdown
    # AlertComponent

    ::: components.alert_component:AlertComponent
        handler: python
        options:
          show_source: true
          heading_level: 2

## 4 Работа с документацией.

### 4.1 Просмотр в реальном времени

bash

mkdocs serve

### 4.2 Сборка документации

bash

rmdir /s /q site # Очистка кэша

mkdocs build # Пересборка

## 5 Частые проблемы и решения

Ошибки импорта:

- Убедитесь в наличии init.py в директориях.

- Проверьте пути в mkdocs.yml.

Предупреждения аннотации типов для параметра:

Убедитесь в наличии аннотации типов для параметра.

## 6 Заключение

Для обновления документации после изменений в коде:

- Внесите изменения в docstrings Python-кода.

- Обновите соответствующие .md-файлы.

- Пересоберите документацию.