Files
java-word-pdf/docs/operations/docs-site.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

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, не поддерживаются scopes pages/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 как статика.