Руководство по документации — BirdLense Hub

Как устроена документация проекта для читателей и контрибьюторов.

Структура

Зона	Назначение
Корень репозитория	`README.md` (EN), быстрый старт, ссылки на `docs/`
`docs/`	Подробные гайды, справка, troubleshooting
`docs/archive/`	Исторические заметки (по желанию)

Навигация: с docs/README.md.

Статический сайт документации (MkDocs + GitHub Pages)

Версия Python: в Docker-образе приложения BirdLense — Python 3.11 (база Ultralytics). MkDocs для этого репозитория собирается на Python 3.12 (как в CI job docs) — используйте отдельный venv (например .venv-docs); не смешивайте с интерпретатором внутри контейнера приложения.

В корне репозитория лежит mkdocs.yml: тема Material, каталог исходников — docs/, структура nav согласована с SITE_MAP.ru.md. Файлы политики и метаданных в корне репозитория (contributing, security policy, changelog, OpenAPI) на сайте открываются через короткие страницы в docs/project/, чтобы ссылки из docs/ не уходили в ../ (так ломается публикация на GitHub Pages).

Сборка локально

python3 -m venv .venv-docs
.venv-docs/bin/pip install -r requirements-docs.txt
.venv-docs/bin/mkdocs serve   # http://127.0.0.1:8000

Каталог site/ в git не коммитится (см. .gitignore).

Не входят в опубликованный сайт (exclude_docs в корневом mkdocs.yml): docs/archive/**, docs/article/** (черновики публикаций) и CONSILIUM_AUDIT.ru.md (исторический аудит; ссылка из archive/README).

Публикация (CI)

Workflow .github/workflows/docs-pages.yml:

При push в main или dev при изменениях в docs/**, mkdocs.yml, VERSION, requirements-docs.txt или scripts/check-docs-version.py (или вручную: Actions → Documentation site → Run workflow) сайт собирается каждый раз.
Перед сборкой: python3 scripts/check-docs-version.py — строка из корневого VERSION должна быть в mkdocs.yml (как минимум extra.site_version; верхний баннер — overrides/main.html, блок {% block announce %}, версия из config.extra.site_version).
Сборка: mkdocs build --strict (битые ссылки и ошибки навигации роняют CI).
Деплой на GitHub Pages выполняется только для ветки main.

Настройки репозитория (один раз): Settings → Pages → Build and deployment → Source: GitHub Actions. При первом запуске может понадобиться подтвердить окружение github-pages для workflow.

Если на опубликованном сайте всё ещё старая версия в баннере, проверьте, что в main попал актуальный mkdocs.yml и что workflow Documentation site завершился успешно (обновление Pages может занять несколько минут).

Контент для сообщества, сайта и статей

Материал	Назначение
OVERVIEW	Текст «что и зачем» — главная, статьи
README в `docs/`	Оглавление по темам; навигация сайта — `mkdocs.yml` в корне
SITE_MAP	Готовое сопоставление разделов и файлов
INSTALL + SCENARIOS	Быстрый старт и туториалы
FEATURES	Витрина возможностей
ARCHITECTURE	Техническая глубина
`app/web/openapi.yaml`	Контракт API; на статическом сайте: OpenAPI (Redoc) (iframe → `openapi.html`)

Стиль: на «вы», короткие блоки, таблицы; без внутреннего жаргона планирования в пользовательских страницах.

Чеклист ревьюера (перед мержем доков)

[ ] Основной язык — EN в *.md; при смене структуры обновлён *.ru.md.
[ ] Только плейсхолдеры, без реальных IP/путей.
[ ] Перекрёстные ссылки на ту же локаль, где есть пара.
[ ] Длинные инструкции (Colab): ячейки исполнимы; тексты print согласованы с языком страницы.
[ ] Обновлены README.md и I18N_STATUS.md при новой странице.
[ ] Корневой mkdocs.yml: новая страница в английском nav и в секции Русский (или осознанно только в репозитории).
[ ] SITE_MAP.md и SITE_MAP.ru.md совпадают с боковым меню.

Языки

Английский — основной язык для новых и поддерживаемых страниц (*.md).
Русский — в парных файлах (*.ru.md), где есть перевод.
В начале каждой пары — ссылка на другую версию (как в INSTALL.md).

Документы, где в *.md пока только RU, перечислены в I18N_STATUS.md; цель — EN основной + опционально RU.

Безопасность в примерах

Не коммитить реальные хосты, пути, токены и ключи. Использовать плейсхолдеры:

Тип	Пример
Хост	`YOUR_HOST`, `localhost`
Путь на сервере	`YOUR_REMOTE_DIR`
Имя в SSH config	`YOUR_SSH_HOST`
Секреты	`your-secret-token`, `your-api-key`
Публичный URL	`https://your-birdlense.example.com`

Полная таблица: OPEN_SOURCE_PREP.md, раздел «Placeholders».

Как править документацию

Инструктивный тон: что сделать, а не история разработки.
Согласованность INSTALL, CONFIGURATION, SCENARIOS, TROUBLESHOOTING (перекрёстные ссылки).
После смены заголовков — проверить внутренние ссылки.
Новый гайд — строка в docs/README.md и обновление I18N_STATUS.md.

Нормы репозитория: Contributing.

Ключевые документы

Тема	Вход (EN)
Обзор и аудитория	OVERVIEW.md
Установка / деплой	INSTALL.md
Сценарии	SCENARIOS.md
Конфигурация	CONFIGURATION.md
Глоссарий	GLOSSARY.ru.md
Тесты	TESTING.md
Проблемы	TROUBLESHOOTING.md
Локальная разработка	LOCAL_DEV.md
Архитектура	ARCHITECTURE.md
API (обзор)	API.md
Доступ и роли	ACCESS_CONTROL.md
Карта сайта	SITE_MAP.md
Обучение (Colab)	TRAINING.md
Датасеты	DATASETS.md
Версионирование	VERSIONING.md
Roadmap	ROADMAP.md
Анализ безопасности	SECURITY.md
Чеклист open-source	OPEN_SOURCE_PREP.md
Статус локализации	I18N_STATUS.md