- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
4.3 KiB
Этот сайт документации
Статический сайт (MkDocs Material) собирается из docs/ этого репозитория и
раздаётся nginx-контейнером на rpi-хосте LAN-сервера:
- адрес:
http://192.168.88.23:9012/(LAN; наружу не публикуется); - статика:
/home/pjandro/srv/wordpdf-docs/(rsync без рестарта контейнера); - javadoc публичного API:
/apidocs/index.html.
Публикация (с хоста, из репозитория)
./mise.sh run docs-install # разово: venv docs/.venv + mkdocs-material
./mise.sh run docs-deploy # javadoc → strict-build → rsync в ~/srv/wordpdf-docs
docs-deploy выполняет фиксированный порядок: mvn javadoc:javadoc → копия
wordpdf-core/target/site/apidocs → docs/apidocs → mkdocs build --strict →
rsync -a --delete site/ ~/srv/wordpdf-docs/. Рестарт сервиса не нужен —
nginx раздаёт файлы с смонтированного тома. Strict-сборка ловит битые ссылки и
страницы вне nav.
Dev-цикл: ./mise.sh run docs-serve → http://127.0.0.1:8000/ (live-reload).
Сервис отдачи
Rootless podman (nginx-контейнер) под user-systemd (linger=yes). Юнит
~/.config/systemd/user/wordpdf-docs.service (вне git; канон текста — здесь):
[Unit]
Description=Word PDF — сайт документации (nginx static, :9012)
[Service]
# podman run без -d — foreground, systemd видит основной процесс
ExecStart=/usr/bin/podman run --name wordpdf-docs --replace -p 9012:80 -v /home/pjandro/srv/wordpdf-docs:/usr/share/nginx/html:ro docker.io/library/nginx:alpine
ExecStopPost=/usr/bin/podman rm -f wordpdf-docs
Restart=on-failure
RestartSec=5
TimeoutStopSec=30
[Install]
WantedBy=default.target
Разовая установка (на хосте 192.168.88.23):
podman pull docker.io/library/nginx:alpine
install -d /home/pjandro/srv/wordpdf-docs
systemctl --user daemon-reload
systemctl --user enable --now wordpdf-docs.service
Проверка/управление:
systemctl --user status wordpdf-docs.service
journalctl --user -u wordpdf-docs.service -n 50
curl -sf -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9012/
Порт 9012: соседние 9010/9011 заняты стендами конвертера (конвенция сети), 8000 —
dev-preview. Наружу (wan) не публикуем; наружный nginx pjandro.ru при желании
добавит владелец сервера отдельно.
Почему не Gitea Pages
Публиковать на инстансе git.pjandro.ru (Gitea 1.26.4) проверенным способом «Pages»
нельзя — встроенного Pages в этой сборке нет:
- в swagger инстанса отсутствует эндпоинт
/repos/{owner}/{repo}/pages, в config cheat sheet —ENABLE_PAGES/PAGES_DOMAIN; - FAQ инстанса: «Gitea doesn't provide a built-in Pages server»;
- в Gitea Actions игнорируется
jobs.*.environment, не поддерживаются scopespages/deployments; тандемupload-pages-artifact+deploy-pagesнеработоспособен (upload-artifact@v4не поддерживается,@v3подвешивается).
Поэтому публикация — локальная задача docs-deploy на том же хосте, где живёт
сервис; CI не участвует (docs-файлы не требуют гейтов).
Что входит в сайт / не входит
В сайт попадают все страницы docs/, кроме docs/agent/, docs/standards/
и docs/requirements.txt (exclude_docs в mkdocs.yml) — это внутренние
справочники и спецификации, на них ведут внешние ссылки на Gitea
(Внутренние справочники). Каталог docs/apidocs/
(gitignored) заполняется задачей docs-deploy и копируется mkdocs как статика.