@coopenomics/docs — компонент документации всей платформы. Использует MkDocs Material для генерации статического сайта из markdown-файлов. Включает руководства для пайщиков, администраторов и разработчиков, протоколы, API-документацию и глоссарий.

Публикация на GitHub Pages выполняется через gh-pages.

Возможности

MkDocs Material — современная тема с тёмным/светлым режимом, навигацией, поиском и подсветкой кода
Макросы — поддержка mkdocs-macros-plugin через main.py для динамического контента
Многоразделовая структура — руководства для участников, администраторов, членов совета и разработчиков
Автосинхронизация — скрипт sync-docs.sh подтягивает документацию из компонентов sdk и controller
GitHub Pages — автоматическая публикация собранной документации

Предварительные требования

Python 3.8+
MkDocs и плагины (см. раздел «Установка»)
Node.js (только для публикации на GitHub Pages)

Установка

Python-зависимости

python -m venv venv
source venv/bin/activate
pip install mkdocs-material mkdocs-macros-plugin mkdocs-section-index mkdocs-blog pymdown-extensions

Если используются дополнительные плагины, проверьте их наличие в mkdocs.yml и установите через pip.

Node.js-зависимости (для публикации)

pnpm install --filter @coopenomics/docs

Скрипты

Скрипт	Описание
`mkdocs serve`	Локальный запуск сервера документации
`mkdocs build`	Сборка статического сайта в директорию `site/`
`./sync-docs.sh`	Синхронизация SDK и Controller документации
`pnpm run publish`	Публикация на GitHub Pages через `gh-pages`

Синхронизация документации

Скрипт sync-docs.sh автоматически подтягивает и копирует документацию из связанных компонентов:

Копирует сгенерированную документацию SDK в docs/sdk/
Генерирует документацию контроллера и копирует в docs/graphql/

./sync-docs.sh

Архитектура

├── mkdocs.yml                 # Конфигурация MkDocs
├── main.py                    # Макросы для mkdocs-macros-plugin
├── sync-docs.sh               # Скрипт синхронизации документации
├── docs/                      # Исходные markdown-файлы
│   ├── participants/          # Руководство для пайщиков
│   │   ├── getting-started/   # Начало работы
│   │   ├── financial-operations/ # Финансовые операции
│   │   └── documents-and-applications/ # Документы
│   ├── manual/                # Руководство администратора
│   │   ├── about-mono/        # О платформе
│   │   ├── participants/      # Управление участниками
│   │   ├── documents/         # Документооборот
│   │   ├── soviet/            # Управление советом
│   │   └── admins/            # Администраторы
│   ├── new/                   # Новые разделы документации
│   ├── sdk/                   # Сгенерированная документация SDK
│   ├── graphql/               # Сгенерированная документация API
│   └── vocabulary.md          # Глоссарий терминов
├── overrides/                 # Пользовательские шаблоны
├── site/                      # Собранная статика (автогенерация)
└── package.json

Локальная разработка

# Активируйте виртуальное окружение Python
source venv/bin/activate

# Запустите dev-сервер
mkdocs serve

Документация будет доступна в браузере (адрес указывается в выводе команды mkdocs serve).

Лицензия

BY-NC-SA 4.0