docs(todo): пересборка и публикация документации стендов — отдельная работа

В docs/TODO/docs_publish_stale_versions.md зафиксировано: - проблема: на nubes-test в примерах версия 5.0.5 (в profile.env 3.0.0), на nubes-dev 2.0.23 (2.0.0), prod 1.0.0 совпадает; - причина: {{VERSION}} подставляется при сборке из profile.env (04:185-198), сайты не пересобирались после смены нумерации 2026-09-03; - что сделать: 04 --profile dev/test + заливка mc mirror с ВМ 5.172.178.213 (команды из DOCS_PIPELINE/README.md), затем проверка версий на живых страницах; - что уедет заодно: правки curated/crud/three_apps.md (ab9f7d2, 39849bf), страницы k8svalkey/k8s_ziti_controller/nodered/nifi; - предупреждения: публикация = деплой (только по команде), публикация без версии в URL со стиранием старых файлов, риск root-овой сборки site/. В HISTORY-записи раздела 4 добавлена ссылка на этот TODO. Проверено: 2 блока кода (чётно), раздел «Связанные документы» на месте.
2026-10-02 08:22:07 +03:00
parent 6015a7ebe8
commit 07773ed963
2 changed files with 80 additions and 0 deletions
@@ -100,6 +100,9 @@
 `./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/test`, затем заливка
 с ВМ `5.172.178.213` (`DOCS_PIPELINE/README.md`, раздел «Публикация: где запускать `mc mirror`»).

+Задача вынесена отдельной работой: **`docs/TODO/docs_publish_stale_versions.md`** — там команды,
+порядок заливки и что ещё уедет вместе с пересборкой. Сейчас не делаем.
+
 ## 5. Мои ошибки в этой работе

 - Разделение `pg/` + `apps/` назвал «разделение ответственности, decoupling» — терминологически
@@ -0,0 +1,77 @@
+# Пересобрать и опубликовать документацию стендов (на сайтах старые версии провайдера)
+
+Дата: 2026-10-02 | Статус: не начато (отдельная работа, по отдельной команде)
+
+## Суть проблемы
+
+Опубликованные сайты документации отдают **устаревшую версию провайдера** в примерах
+(`required_providers … version = …`).
+
+| Стенд | На сайте | `VERSION` в `TOOLS/config/<стенд>/profile.env` | Итог |
+|---|---|---|---|
+| `nubes-test` → `https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-test/` | **5.0.5** | 3.0.0 | устарел |
+| `nubes-dev` → `https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-dev/` | **2.0.23** | 2.0.0 | устарел |
+| `nubes` (prod) → `https://tf-docs.nodejsk8s.dev.nubes.ru/nubes/` | 1.0.0 | 1.0.0 | совпадает |
+
+Проверялось на странице `…/<стенд>/curated/postgres/pg_user_db/` (в исходнике там
+плейсхолдер `{{VERSION}}`).
+
+## Причина
+
+В исходниках `docs/` версии нет — при сборке плейсхолдеры подставляются значениями из
+профиля стенда (`TOOLS/scripts/04_build_and_publish_docs.sh:185-198`). Значит сайты
+собраны **до** смены нумерации версий (2026-09-03) и с тех пор не пересобирались.
+
+Дополнительные подтверждения старости публикации:
+
+- на `nubes-test` нет страниц, которые уже есть на `nubes-dev`: `k8svalkey`,
+  `k8s_ziti_controller`, `nodered`, `nifi`;
+- на `nubes-test` нет правок страницы `curated/crud/three_apps.md` (коммит `ab9f7d2`);
+- локальная сборка `site/` (2026-09-28 09:40) — сборка dev-стенда, строки `5.0.5` в ней
+  нет, то есть на S3 лежит сборка **старше** этого `site/`.
+
+## Что сделать
+
+1. Для каждого устаревшего стенда — сборка и публикация:
+
+```bash
+./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/dev
+./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/test
+```
+
+2. Заливка на S3 делается **с ВМ `5.172.178.213`** (у локальной сети S3 рвёт большие
+   ответы), полный порядок — в `DOCS_PIPELINE/README.md`, раздел «Публикация: где
+   запускать `mc mirror`»:
+
+```bash
+tar -C site -cf - . | ssh naeel@5.172.178.213 'rm -rf ~/tmp-docs-site && mkdir -p ~/tmp-docs-site && tar -C ~/tmp-docs-site -xf -'
+ssh naeel@5.172.178.213 'mc mirror --overwrite --remove ~/tmp-docs-site/ registry/terraform-registry/docs/<namespace>/nubes/'
+ssh naeel@5.172.178.213 'mc mirror --overwrite --remove "registry/terraform-registry/docs/<namespace>/nubes/" /var/www/tf-docs/<namespace>/'
+```
+
+3. Проверить результат на живом сайте: на странице `…/<стенд>/curated/postgres/pg_user_db/`
+   версия должна совпасть с `VERSION` из `profile.env` (`dev=2.0.0`, `test=3.0.0`,
+   `prod=1.0.0`), и должны появиться страницы, которых на стенде не было.
+
+## Заодно уедет (уже закоммичено в `docs/`)
+
+- `curated/crud/three_apps.md` — страница переписана под схему `pg/` + `apps/`
+  (коммит `ab9f7d2`) и дополнена разделом «Что пользователь задаёт сам» (коммит `39849bf`).
+- страницы, добавленные с прошлой публикации (`k8svalkey`, `k8s_ziti_controller`,
+  `nodered`, `nifi` — уже видны на dev, но не на test).
+
+## Осторожно
+
+- Публикация — это деплой: выполнять только по прямой команде владельца.
+- `publish-docs.sh` публикует **без версии в URL** (`mc mirror --overwrite --remove`),
+  старые файлы удаляются — после публикации проверить, что живые разделы на месте.
+- Если `site/` собирался docker-ом от root, mkdocs не сможет перезаписать каталог:
+  `sudo rm -rf site` или удалить через контейнер (см. `DOCS_PIPELINE/README.md`).
+
+## Связанные документы
+
+- `HISTORY/50_docs/2026-10-02_crud_docs_page_and_manual_pages_pipeline.md` — раздел 4:
+  как это обнаружено (проверка страницы `nubes-test/curated/postgres/pg_user_db/`).
+- `DOCS_PIPELINE/README.md` — актуальное описание сборки и публикации.
+- `HISTORY/50_docs/2026-10-02_s3_static_website_docs_hosting.md` — хостинг документации
+  из S3 (находки по static website на RGW).