111 lines
3.4 KiB
Markdown
111 lines
3.4 KiB
Markdown
# Документация проекта: настройка 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-файлы.
|
||
|
||
- Пересоберите документацию. |