fix(docs): remove stand-specific hardcodes

2026-09-03 16:14:28 +03:00
parent 6bf514e03a
commit aa0f7f6402
7 changed files with 170 additions and 51 deletions
@@ -0,0 +1,67 @@
+# 2026-09-03 — Устранение хардкодов документации и публикация DEV
+
+## Найденная причина
+
+Общие материалы `docs/30_registry/` и `docs/curated/` копировались в каждый `generated/<stand>/docs/`, но подстановка выполнялась только для части `getting-started.md`. Поэтому в DEV попадали TEST-значения:
+
+- TEST provider source;
+- `5.0.5`;
+- TEST API endpoint;
+- `deck-test.ngcloud.ru`.
+
+Дополнительно `02_generate_resources_and_docs_v2.sh` не очищал старые generated-файлы. Ресурс, отсутствующий в текущем `services_list.txt`, мог остаться от предыдущей генерации.
+
+## Изменения
+
+- Общие документы используют placeholders:
+  - `{{NAMESPACE}}`;
+  - `{{VERSION}}`;
+  - `{{PROVIDER_SOURCE}}`;
+  - `{{NUBES_API_ENDPOINT}}`;
+  - `{{DASHBOARD_URL}}`.
+- `04_build_and_publish_docs.sh` подставляет значения рекурсивно во все скопированные Markdown-файлы.
+- Добавлена проверка чужих namespace, API/dashboard host и старого `registry.kube5s.ru` до сборки.
+- Профиль стал обязательным; обязательные значения не берутся из PROD fallback.
+- `02_generate_resources_and_docs_v2.sh` очищает только собственный `generated/<stand>/docs` перед генерацией.
+- `docs-generator` больше не содержит DEV default для API/provider source.
+- Базовый `mkdocs.yml` больше не содержит versioned URL.
+
+## Проверки
+
+- `bash -n` для обоих docs scripts — PASS.
+- `go test ./...` и `go build ./...` в `TOOLS/docs-generator` — PASS.
+- DEV regeneration — PASS.
+- DEV MkDocs build — PASS; contamination check — PASS.
+- В DEV отсутствуют `5.0.5`, TEST API, `deck-test.ngcloud.ru` и `registry.kube5s.ru`.
+- Legacy generated `vc_vm_v2` удалён чистой генерацией, так как отсутствует в актуальном `services_list.txt`.
+
+## Публикация
+
+Локальный рекурсивный S3 mirror завершался `unexpected EOF`, поэтому exit code штатного скрипта нельзя считать достаточным подтверждением загрузки. Проверенный артефакт `site/` был передан на ВМ `5.172.178.213` по SSH и атомарно установлен в:
+
+```text
+/var/www/tf-docs/nubes-dev/
+```
+
+На ВМ проверены страницы getting-started и curated PostgreSQL:
+
+- namespace `nubes-dev`;
+- provider version `2.0.0`;
+- DEV API endpoint;
+- DEV dashboard URL;
+- отсутствие TEST-значений.
+
+Legacy versioned каталоги TEST ранее удалены и после публикации отсутствуют:
+
+```text
+/var/www/tf-docs/nubes-test/5.0.5
+/var/www/tf-docs/nubes-test/5.0.57
+```
+
+Публичный путь документации:
+
+```text
+https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-dev/
+```
+
+Публичный `curl` завершался timeout на большом HTML; содержимое активного зеркала ВМ проверено напрямую.