Документация для платформы Citeck — low-code платформа для управления бизнес-процессами, документами и задачами.
- Python 3.12+
- pre-commit — git-хуки для автоматического сжатия изображений
- pngquant — сжатие PNG
- jpegoptim — сжатие JPEG
- gifsicle — сжатие GIF
- webp — сжатие WebP (cwebp)
brew install pngquant jpegoptim gifsicle webp pre-commitsudo apt install pngquant jpegoptim gifsicle webp
pip install pre-commitchoco install pngquant jpegoptim gifsicle libwebp
pip install pre-commitИли через Scoop:
scoop install pngquant jpegoptim gifsicle libwebp
pip install pre-commitРекомендуется устанавливать зависимости в виртуальное окружение — на современных macOS/Linux прямой pip install часто блокируется (PEP 668, ошибка externally-managed-environment).
Окружение создаётся в корне репозитория, а не в docs/: каталог docs/ — это источник для Sphinx, и venv внутри него будет просканирован как документация (в лог посыпятся ошибки из site-packages).
cd /путь/к/ecos-docs
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r docs/requirements.txt
pre-commit installПеред каждой сборкой активируйте окружение командой source .venv/bin/activate.
После git pull повторяйте pip install -r docs/requirements.txt — список зависимостей меняется, а существующее окружение само не обновляется.
После pre-commit install каждый коммит с изображениями будет автоматически сжимать их.
Если pre-commit хук не настроен, можно сжать изменённые изображения перед коммитом вручную:
python3 scripts/compress-images.py path/to/image1.png path/to/image2.jpgДля сжатия всех изображений в репозитории:
pre-commit run compress-images --all-filessource .venv/bin/activate
cd docs
make htmlРезультат сборки будет в _build/html/. Для просмотра в браузере:
python3 -m http.server 8030 --directory _build/html/Затем откройте http://localhost:8030.
Для сборки PDF используется LaTeX-сборщик Sphinx с движком XeLaTeX (нужен для корректного отображения кириллицы).
Нужны:
- TeX Live с XeLaTeX,
latexmkи шрифтами для кириллицы; rsvg-convertизlibrsvg—xelatexне умеет встраивать SVG напрямую, Sphinx конвертирует их в PDF черезsphinxcontrib-svg2pdfconverter;- ImageMagick (
convert/magick) — для расширенияsphinx.ext.imgconverter, которое автоматически ужимает слишком большие растровые изображения, чтобыxelatexне падал сDimension too large.
brew install --cask mactex-no-gui
brew install librsvg imagemagickИли минимальный вариант TeX Live:
brew install --cask basictex
sudo tlmgr update --self
sudo tlmgr install latexmk xetex collection-fontsrecommended collection-langcyrillic
brew install librsvg imagemagicksudo apt install texlive-xetex texlive-fonts-recommended texlive-lang-cyrillic latexmk librsvg2-bin imagemagickУстановите MiKTeX или TeX Live — недостающие пакеты подтянутся автоматически при первой сборке. Дополнительно нужны rsvg-convert из librsvg и ImageMagick (например, choco install rsvg-convert imagemagick или scoop install librsvg imagemagick).
source .venv/bin/activate
cd docs
make latexpdfГотовый PDF будет доступен по пути _build/latex/citeck.pdf. Сборка идёт долго — около 25 минут (примерно 2700 страниц, ~80 МБ), latexmk делает 3 прохода. Предупреждения Overfull \hbox, Underfull \vbox, Hyper reference ... undefined и Missing character — нормальны и на результат не влияют.
| Ошибка | Причина и решение |
|---|---|
sphinx-build: command not found |
Не активировано окружение — source .venv/bin/activate из корня репозитория. |
Не удалось загрузить расширение <имя> (exception: No module named ...) |
Окружение устарело относительно docs/requirements.txt — выполните pip install -r docs/requirements.txt. Пересоздание venv поверх существующего каталога зависимости не ставит. |
ERROR из site-packages/... в логе сборки |
Виртуальное окружение создано внутри docs/ — Sphinx сканирует его как источник. Создавайте venv в корне репозитория. |
xelatex: command not found (macOS) |
После установки MacTeX добавьте /Library/TeX/texbin в PATH или откройте новую сессию терминала. |