# Этот сайт документации Статический сайт (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 как статика.