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:
@@ -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 как статика.
|
||||
Reference in New Issue
Block a user