Документация проекта: настройка 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-файлы.

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