b3511f8b74
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
# Этот сайт документации
|
|
|
|
Статический сайт (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 как статика.
|