docs: сайт документации на MkDocs Material

- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+88
View File
@@ -0,0 +1,88 @@
# Этот сайт документации
Статический сайт (MkDocs Material) собирается из `docs/` этого репозитория и
раздаётся nginx-контейнером на rpi-хосте LAN-сервера:
- адрес: **`http://192.168.88.23:9012/`** (LAN; наружу не публикуется);
- статика: `/home/pjandro/srv/wordpdf-docs/` (rsync без рестарта контейнера);
- javadoc публичного API: [`/apidocs/index.html`](/apidocs/index.html).
## Публикация (с хоста, из репозитория)
```bash
./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; канон текста — здесь):
```ini
[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`):
```bash
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
```
Проверка/управление:
```bash
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
([Внутренние справочники](../internal-guides.md)). Каталог `docs/apidocs/`
(gitignored) заполняется задачей `docs-deploy` и копируется mkdocs как статика.