docs: add DOCS_PIPELINE — инструкция по генерации и заливке MkDocs-документации

2026-09-01 08:43:55 +03:00
parent ed568a867a
commit b3342bc0c5
2 changed files with 168 additions and 0 deletions
@@ -0,0 +1,134 @@
+# Документация MkDocs: генерация и заливка в реестр
+
+> ⛔⛔⛔ **НЕ ЛОМАТЬ РАБОТАЮЩИЙ КОД** ⛔⛔⛔
+>
+> Эта папка — **справочная**. Скрипты пайплайна в `TOOLS/scripts/` и `scripts/`
+> работают и должны оставаться **нетронутыми**.
+> Любая правка в них — только после явного «делай» и с проверкой, что ничего не сломалось.
+
+---
+
+## Что здесь
+
+Всё про **генерацию документации** провайдера Nubes, **сборку** MkDocs-сайта
+и **заливку** статики в S3-реестр.
+
+## Два независимых потока
+
+### A. Генерация Markdown-доков по ресурсам (API → YAML → .md)
+
+| Шаг | Скрипт | Что делает |
+|---|---|---|
+| 1 | `TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/<стенд>` | Тянет спецификации из API стенда → `generated/<стенд>/resources_yaml/` |
+| 2 | `TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/<стенд>` | YAML → Go-код (`TOOLS/bin/resource-generator`) + Markdown-доки (`TOOLS/bin/docs-generator`) в `generated/<стенд>/docs/` |
+| 3 (опц.) | `TOOLS/scripts/05_generate_docs_llm.py` | Прогоняет .md через LLM (улучшение описаний) |
+| 4 | `TOOLS/scripts/03_build_and_upload_provider.sh --profile ... <ver>` | Сборка провайдера + GPG-подпись + заливка бинарников в S3 |
+
+### B. Сборка MkDocs-сайта + заливка доков в S3
+
+| Шаг | Скрипт | Что делает |
+|---|---|---|
+| 1 | `TOOLS/scripts/04_build_and_publish_docs.sh --profile ... <ver>` | Генерирует `.mkdocs.tmp.yml` (версия/`docs_dir`/nav), собирает сайт (docker → venv → system mkdocs) в `site/` |
+| 2 | `scripts/publish-docs.sh` | Заливает `site/` в S3 (`mc cp --recursive` + `mc policy set public`) |
+| 3 (опц.) | `scripts/publish-doc-page.sh` | Заливка **одной** страницы |
+| CI | `.github/workflows/publish-docs.yml` | Авто-публикация по git-тегу `v*.*.*` |
+
+---
+
+## Команды (полный цикл, стенд = dev/test/prod)
+
+```bash
+# DEV (пример)
+./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev
+./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev
+./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 3.1.13
+./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/dev 3.1.13
+```
+
+**Быстрая заливка** (YAML/Go уже сгенерированы, не менялись) — только шаг 3/4:
+```bash
+./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/test 5.1.17
+./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/test 5.1.17
+```
+
+### Ручная заливка доков (рабочий способ)
+
+```bash
+# S3-креды из secrets/.s3cfg_registry (или env S3_ENDPOINT/S3_ACCESS_KEY/S3_SECRET_KEY)
+/home/naeel/terra/scripts/publish-docs.sh \
+  site \
+  tf-registry.containerk8s.services.ngcloud.ru \
+  nubes nubes 2.0.2
+```
+
+---
+
+## Список файлов
+
+### Скрипты (пайплайн)
+- `TOOLS/scripts/01_generate_yamls.sh`
+- `TOOLS/scripts/02_generate_resources_and_docs_v2.sh`
+- `TOOLS/scripts/03_build_and_upload_provider.sh`
+- `TOOLS/scripts/04_build_and_publish_docs.sh`
+- `TOOLS/scripts/05_generate_docs_llm.py`
+- `TOOLS/scripts/build-provider.sh`
+- `scripts/publish-doc-page.sh`
+- `scripts/publish-docs.sh`  ← ⚠️ см. «Известная проблема» ниже
+
+### Генераторы (Go-бинарники)
+- `TOOLS/bin/resource-generator`
+- `TOOLS/bin/docs-generator`
+- `TOOLS/bin/yaml-generator`
+
+### Конфиг
+- `mkdocs.yml` — конфиг MkDocs (site_url, nav, тема material)
+- `TOOLS/config/registry.env` — реестр (`REGISTRY_HOSTNAME`, `S3_ENDPOINT`, `S3_BUCKET`)
+- `TOOLS/config/{dev,test,prod}/profile.env` — стенд (`NUBES_API_ENDPOINT`, `NAMESPACE`, `VERSION`)
+- `TOOLS/config/{dev,test,prod}/services_list.txt`
+- `TOOLS/config/{dev,test,prod}/operation_timeouts.json`
+
+### Секреты
+- `secrets/{dev,test,prod}.token`
+- `secrets/private_key.asc` — GPG-подпись
+- `secrets/.s3cfg_registry` — S3-креды
+
+### Контент / ассеты
+- `docs/` — ручные источники (`index.md`, `curated/`, `help/`, `30_registry/` и др.)
+- `docs/30_registry/` — `guides/`, `resources/`, `assets/`, `javascripts/fix-slash.js`
+- `generated/<стенд>/docs/` — сгенерированные доки (включая `_nav_fragment.yml`)
+- `site/`, `site_test/` — результат сборки
+
+---
+
+## S3 / бакеты
+
+| Что | Бакет | Путь |
+|---|---|---|
+| **Документация** | `terraform-registry` | `docs/<namespace>/<name>/<version>/` |
+| **Бинарники провайдера** | `nubes-terraform-registry` | `<host>/<namespace>/<name>/<version>/` |
+
+- Эндпоинт S3: `https://s3.msk-1.ngcloud.ru`
+- Хост реестра: `tf-registry.containerk8s.services.ngcloud.ru`
+- Клиент: `mc` (MinIO), алиасы `prod-s3`/`reg`/`registry`/`tfreg`
+
+---
+
+## ⚠️ Известная проблема: `scripts/publish-docs.sh` отсутствует в этом репозитории
+
+1. Скрипт `scripts/publish-docs.sh` **удалён** из `/home/naeel/tf_provider`
+   коммитом `c2438f5` (2026-07-05, «superseded by devops/»).
+2. Но `TOOLS/scripts/04_build_and_publish_docs.sh` (строка ~280) и
+   `.github/workflows/publish-docs.yml` (строка ~54) **до сих пор вызывают**
+   `./scripts/publish-docs.sh`.
+3. **Следствие:** запуск `04` из этого репозитория соберёт сайт, но упадёт
+   на шаге заливки (`No such file or directory`). CI по тегу — аналогично.
+
+**Рабочая копия скрипта живёт в старом репозитории** (отдельный git, не клон):
+- `/home/naeel/terra/scripts/publish-docs.sh`
+- архив: `/home/naeel/terraform__OFF/scripts/publish-docs.sh`
+
+Копия этого скрипта сохранена рядом: [`publish-docs.sh`](./publish-docs.sh)
+
+### Варианты устранения (только после «делай»)
+1. Восстановить `scripts/publish-docs.sh` в это репозиторий (из копии рядом или из git `c2438f5^`).
+2. Инлайнить заливку прямо в `04_build_and_publish_docs.sh` (как уже сделано в `publish-doc-page.sh`).
@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Заливка собранного MkDocs-сайта (site/) в S3-реестр.
+# Копия рабочего скрипта из старого репозитория /home/naeel/terra/scripts/publish-docs.sh.
+# ⚠️ НЕ ЛОМАТЬ РАБОТАЮЩИЙ КОД: этот файл — справочная копия, не подменяет пайплайн.
+
+# Usage: publish-docs.sh <site-dir> <registry-host> <namespace> <name> <version>
+SITE_DIR=${1:-site}
+REGISTRY_HOST=${2:-tf-registry.containerk8s.services.ngcloud.ru}
+NAMESPACE=${3:-nubes}
+NAME=${4:-nubes}
+VERSION=${5:-dev}
+
+# Support both S3_* (New Standard) and MINIO_* (Legacy) variables
+ENDPOINT=${S3_ENDPOINT:-${MINIO_ENDPOINT:-}}
+ACCESS_KEY=${S3_ACCESS_KEY:-${MINIO_ACCESS_KEY:-}}
+SECRET_KEY=${S3_SECRET_KEY:-${MINIO_SECRET_KEY:-}}
+
+if [ -z "$ENDPOINT" ] || [ -z "$ACCESS_KEY" ] || [ -z "$SECRET_KEY" ]; then
+  echo "Error: S3_ENDPOINT/S3_ACCESS_KEY/S3_SECRET_KEY must be set"
+  exit 2
+fi
+
+MC_ALIAS=registry
+mc alias set $MC_ALIAS "$ENDPOINT" "$ACCESS_KEY" "$SECRET_KEY" --api S3v4
+TARGET="${MC_ALIAS}/terraform-registry/docs/${NAMESPACE}/${NAME}/${VERSION}/"
+
+# mc создаёт промежуточные каталоги неявно при копировании
+mc cp --recursive "$SITE_DIR/" "$TARGET"
+# Публичная политика на бакет
+mc policy set public "$TARGET" || true
+
+echo "Published docs to: https://${REGISTRY_HOST}/docs/${NAMESPACE}/${NAME}/${VERSION}/"