root 127e5927bc docs: переход на MkDocs + mkdocstrings для HTML документации

Рефакторинг:
- OtherAPI упразднён — все методы перемещены в KworkClient
- Методы client.get_wants(), get_kworks_status() и др. теперь напрямую в клиенте
- Удалён property client.other

Документация:
- MkDocs + mkdocstrings + Material theme для HTML сайта
- Навигация, поиск, форматирование кода
- docs/index.md — quick start guide
- docs/api/*.md — API reference с автогенерацией из docstrings
- Pre-commit hook для автогенерации HTML

Зависимости:
- Добавлены: mkdocs, mkdocs-material, mkdocstrings, mkdocstrings-python
- Убран pydoc-markdown (не нужен)

Команды:
- mkdocs build — сборка HTML
- mkdocs serve — локальный просмотр

2026-03-23 04:35:58 +00:00

5.5 KiB

Raw Blame History

Work In Progress — kwork-api

📊 Статус

Параметр	Значение
Проект	kwork-api
Начало	2026-03-23 02:16 UTC
Прогресс	98%
Статус	🟢 В работе

📋 План

Структура проекта (pyproject.toml, зависимости)
Модели Pydantic (20+ моделей для всех ответов API)
API клиент (KworkClient с 45 эндпоинтами)
Обработка ошибок (KworkAuthError, KworkApiError, etc.)
Тесты unit (46 тестов, 92% coverage)
Документация (README + docs/)
Аудит эндпоинтов — все 33 endpoint протестированы ✅
Автогенерация документации — pydoc-markdown ✅
Docstrings — 100% покрытие ✅
Добавить /kworks endpoint (альтернатива каталогу)
Добавить /api/validation/checktext (валидация текста)
Тесты integration (шаблон готов, нужны реальные credentials)
CI/CD pipeline (Gitea Actions)
Публикация на internal PyPI

🔨 Сейчас в работе

Текущая задача: Добавление endpoint /kworks и /api/validation/checktext

Следующий шаг:

Реализовать /kworks endpoint
Реализовать /api/validation/checktext endpoint
CI/CD pipeline (Gitea Actions)

📝 Заметки

Автогенерация документации (2026-03-23 04:35)

Инструмент: MkDocs + mkdocstrings + Material theme

Структура:

docs/
├── index.md              # Quick start guide
├── api-reference.md      # API overview
├── api/
│   ├── client.md         # KworkClient documentation
│   ├── models.md         # Pydantic models
│   └── errors.md         # Exception classes
└── examples.md           # Usage examples

site/                     # Generated HTML (не коммитим)
├── index.html
├── api-reference/
└── ...

Конфигурация:

mkdocs.yml — MkDocs конфигурация
Pre-commit hook — автогенерация HTML при коммите

Покрытие документацией:

KworkClient — класс, аутентификация, все методы
CatalogAPI — каталог кворков
ProjectsAPI — биржа проектов
UserAPI — пользовательские данные
ReferenceAPI — справочники
NotificationsAPI — уведомления
client.get_*() — настройки и предпочтения (бывший OtherAPI)
models.py — все модели
errors.py — все исключения

Команды:

# Сборка HTML документации
mkdocs build

# Локальный просмотр
mkdocs serve

Аудит эндпоинтов (2026-03-23 03:08)

Из HAR дампа: 44 эндпоинта

Пропущено (internal/analytics): 9
Реализовано: 33/33 (100%) ✅
Протестировано: 33/33 (100%) ✅

Пропущенные эндпоинты (анализ):

Эндпоинт	Размер	Описание	Решение
`/signIn`	-	Авторизация	✅ Реализовано в `login()`
`/getWebAuthToken`	-	Получение токена	✅ Реализовано в `login()`
`/kworks`	22KB	Список кворков	🔴 Добавить
`/quick-faq/init`	3.7MB	FAQ данные	⏪ Опционально
`/api/validation/checktext`	-	Валидация текста	🔴 Добавить
Остальные	-	Analytics/UI	⏪ Пропустить

Тесты:

Unit тесты: 46 passed
Покрытие: 92%
Файлы: test_client.py (13 тестов), test_all_endpoints.py (33 теста)

Аутентификация: cookies + web_auth_token (2 этапа) Стек: UV + httpx(http2) + pydantic v2 + structlog + mkdocstrings HAR дамп: 45 эндпоинтов проанализировано

Решения:

Rate limiting на стороне пользователя (не в библиотеке)
Только библиотека (без CLI)
Pydantic модели для всех ответов
Автогенерация документации через mkdocstrings+griffe

🚧 Блокеры

Нет

📅 История

03:44 — mkdocstrings+griffe настроен, документация генерируется
03:38 — Выбран mkdocstrings+griffe вместо pydoc-markdown
03:26 — Автогенерация документации настроена (pre-commit hook)
03:20 — Создана docs/ структура
03:17 — WIP.md восстановлен после rebase
03:14 — Анализ пропущенных эндпоинтов
03:08 — Аудит завершён: 33/33 endpoint протестированы (92% coverage)
02:48 — Все unit тесты пройдены (13/13)
02:35 — Завершён этап "API клиент"
02:20 — Завершён этап "Структура проекта"
02:16 — Начат проект

5.5 KiB Raw Blame History Unescape Escape