From 72a8a491c6f7284bccdb2e5516248d8eb73d93ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CNaeel=E2=80=9D?= Date: Thu, 3 Sep 2026 07:27:58 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=B0=D0=BA=D1=82=D1=83=D0=B0=D0=BB?= =?UTF-8?q?=D0=B8=D0=B7=D0=B0=D1=86=D0=B8=D1=8F=20DOCS=5FPIPELINE/README?= =?UTF-8?q?=20(=D0=B1=D0=B5=D0=B7=20=D0=B2=D0=B5=D1=80=D1=81=D0=B8=D0=B9,?= =?UTF-8?q?=20=D0=BD=D0=BE=D0=B2=D1=8B=D0=B9=20=D1=85=D0=BE=D1=81=D1=82);?= =?UTF-8?q?=20=D1=81=D1=82=D0=B0=D1=80=D1=8B=D0=B9=20->=20legacy?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DOCS_PIPELINE/README.legacy.md | 134 ++++++++++++++++++++ DOCS_PIPELINE/README.md | 218 ++++++++++++++++----------------- 2 files changed, 237 insertions(+), 115 deletions(-) create mode 100644 DOCS_PIPELINE/README.legacy.md diff --git a/DOCS_PIPELINE/README.legacy.md b/DOCS_PIPELINE/README.legacy.md new file mode 100644 index 0000000..0d00e9b --- /dev/null +++ b/DOCS_PIPELINE/README.legacy.md @@ -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 ... ` | Сборка провайдера + GPG-подпись + заливка бинарников в S3 | + +### B. Сборка MkDocs-сайта + заливка доков в S3 + +| Шаг | Скрипт | Что делает | +|---|---|---| +| 1 | `TOOLS/scripts/04_build_and_publish_docs.sh --profile ... ` | Генерирует `.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////` | +| **Бинарники провайдера** | `nubes-terraform-registry` | `////` | + +- Эндпоинт 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`). diff --git a/DOCS_PIPELINE/README.md b/DOCS_PIPELINE/README.md index 0d00e9b..606fc06 100644 --- a/DOCS_PIPELINE/README.md +++ b/DOCS_PIPELINE/README.md @@ -1,134 +1,122 @@ -# Документация MkDocs: генерация и заливка в реестр +# Документация провайдера Nubes: генерация и публикация -> ⛔⛔⛔ **НЕ ЛОМАТЬ РАБОТАЮЩИЙ КОД** ⛔⛔⛔ -> -> Эта папка — **справочная**. Скрипты пайплайна в `TOOLS/scripts/` и `scripts/` -> работают и должны оставаться **нетронутыми**. -> Любая правка в них — только после явного «делай» и с проверкой, что ничего не сломалось. +> Актуально на 2026-09-03. Историческая версия — [`README.legacy.md`](./README.legacy.md). ---- +## Общая схема -## Что здесь +``` +API стенда ──▶ generated/<стенд>/resources_yaml/ ──▶ generated/<стенд>/docs/ (.md) + │ (docs_dir для MkDocs) + ▼ + MkDocs build ──▶ site/ (HTML) + │ + ▼ + S3 terraform-registry/docs/// (без версии, public) + │ + ▼ + ВМ 5.172.178.213 nginx (зеркало /var/www/tf-docs/) ◀─ под tf_docs (proxy) + │ + ▼ + https://tf-docs.nodejsk8s.dev.nubes.ru// +``` -Всё про **генерацию документации** провайдера Nubes, **сборку** MkDocs-сайта -и **заливку** статики в S3-реестр. +Ключевые принципы: +- **Без версий в URL**: docs публикуются в `docs///` перезаписью (`mc mirror --overwrite --remove`). +- **Вечный бесплатный домен**: `tf-docs.nodejsk8s.dev.nubes.ru//` (managed-кластер → под-прокси → ВМ nginx). +- Имя провайдера (``) во всех стендах — `nubes`; в URL сайта не фигурирует (только ``), в S3-ключе — есть. -## Два независимых потока +## Стенды -### A. Генерация Markdown-доков по ресурсам (API → YAML → .md) +| Стенд | profile.env | Namespace (S3/URL) | API-эндпоинт | Токен | +|---|---|---|---|---| +| dev | `TOOLS/config/dev/profile.env` | `nubes-dev` | `https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc` | `secrets/dev.token` | +| test | `TOOLS/config/test/profile.env` | `nubes-test` | `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc` | `secrets/test.token` | +| prod | `TOOLS/config/prod/profile.env` | `nubes` | `https://lk-api-gateway.ngcloud.ru/api/v1/svc` | `secrets/prod.token` | + +В `profile.env` также: `PROVIDER_NAME=nubes`, пути GPG-ключей, актуальная `VERSION` стенда. + +## Поток 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-код провайдера + Markdown-доки → `generated/<стенд>/docs/` (в т.ч. `_nav_fragment.yml`) | +| 3 (опц.) | `TOOLS/scripts/05_generate_docs_llm.py` | LLM-улучшение описаний `.md` | +| 4 | `TOOLS/scripts/03_build_and_upload_provider.sh --profile ... ` | сборка провайдера + GPG-подпись + бинарники в S3 (не docs) | + +## Поток B — сборка MkDocs-сайта и публикация | Шаг | Скрипт | Что делает | |---|---|---| -| 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 ... ` | Сборка провайдера + GPG-подпись + заливка бинарников в S3 | +| 1 | `TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/<стенд> [ver]` | собирает сайт и публикует (см. ниже) | +| 2 | `scripts/publish-docs.sh ` | заливка `site/` в S3 (см. ниже) | +| 3 (опц.) | `scripts/publish-doc-page.sh` | заливка одной страницы | +| CI | `.github/workflows/publish-docs.yml` | авто-публикация по git-тегу `v*.*.*` | -### B. Сборка MkDocs-сайта + заливка доков в S3 +### Детали шага 04 -| Шаг | Скрипт | Что делает | +1. Читает `profile.env` стенда (`--profile`): `NAMESPACE`, `VERSION`, `NUBES_API_ENDPOINT`, `REGISTRY_HOST` (default `tf-docs.nodejsk8s.dev.nubes.ru`). +2. `MKDOCS_DOCS_DIR` = `generated/<стенд>/docs` — **никогда не сливается с ручным `docs/`**. +3. Копирует ручные ассеты в сгенерированный каталог: `docs/30_registry/` и `docs/curated/` → `generated/<стенд>/docs/`. +4. Подставляет в `generated/<стенд>/docs/guides/getting-started.md` актуальные `version` и `api_endpoint`. +5. Генерирует `.mkdocs.tmp.yml` из `mkdocs.yml`: + - `site_url: https:////`; + - `docs_dir` — относительный на `generated/<стенд>/docs`; + - в `nav` секция «Ресурсы» заменяется на `resources_nav` из `_nav_fragment.yml`. +6. Сборка в `site/` (по убыванию приоритета): docker `squidfunk/mkdocs-material` → `.venv` python mkdocs → системный `mkdocs`. Пинованные версии: `mkdocs==1.6.1`, `mkdocs-material==9.7.3`. +7. Заливка: `./scripts/publish-docs.sh site "$REGISTRY_HOST" "$NAMESPACE" "$PROVIDER_NAME" "$VERSION"`. + - ⚠️ `publish-docs.sh` принимает 4 аргумента (`site host ns name`); 5-й (`VERSION`) игнорируется — публикация всегда без версии. + +### Детали publish-docs.sh (актуальный) + +- Берёт S3-креды из `S3_ENDPOINT/S3_ACCESS_KEY/S3_SECRET_KEY` (или legacy `MINIO_*`), при вызове из `04` — подгружаются из `secrets/.s3cfg_registry`. +- `mc alias set registry --api S3v4`. +- `mc mirror --overwrite --remove "$SITE_DIR/" → registry/terraform-registry/docs///`. +- `mc policy set public` на target. +- Публикация «на месте»: старые файлы удаляются, версий нет. + +## Промежуточные файлы и папки + +| Папка/файл | Назначение | +|---|---| +| `generated/<стенд>/resources_yaml/` | сырые YAML-спеки из API (шаг A1) | +| `generated/<стенд>/docs/` | сгенерированные Markdown + `_nav_fragment.yml` (docs_dir для MkDocs) | +| `site/` | результат сборки MkDocs (HTML), заливается в S3 | +| `site_test/` | тестовая сборка по `.mkdocs.docs_test.yml` | +| `docs/` | ручные источники (`index.md`, `curated/`, `help/`, `30_registry/`); внутренние разделы (`00_overview`, `20_discovery`, `40_analysis`, `50_history`, `60_strategy`, `70_api`, `help/*`, `README.md`, `ai_universal_provider_gen.md`) исключаются через `exclude_docs` | +| `scripts/publish-docs.sh` | актуальная заливка docs в S3 (без версии) | +| `scripts/publish-doc-page.sh` | заливка одной страницы | +| `TOOLS/config/<стенд>/profile.env` | параметры стенда (endpoint, NAMESPACE, VERSION, токен, GPG) | +| `TOOLS/config/registry.env`, `services_list.txt`, `operation_timeouts.json` | конфиги реестра/генерации | +| `TOOLS/bin/` | генераторы: `resource-generator`, `docs-generator`, `yaml-generator` | +| `secrets/{dev,test,prod}.token`, `.s3cfg_registry`, `private_key.asc` | токены API, S3-креды, GPG | +| `mkdocs.yml` | базовый конфиг MkDocs (тема material, exclude_docs, extra) | +| `.mkdocs.tmp.yml` | генерируется в 04, удаляется по trap | +| `.mkdocs.docs_test.yml` | конфиг тестовой сборки (site_test) | +| `DOCS_PIPELINE/publish-docs.sh` | ⚠️ легаси-копия старого скрипта (с версией, `mc cp`); **не использовать** | + +## S3 и хостинг + +| Что | Бакет | Ключ | |---|---|---| -| 1 | `TOOLS/scripts/04_build_and_publish_docs.sh --profile ... ` | Генерирует `.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*.*.*` | +| Документация | `terraform-registry` (public) | `docs///` — без версии | +| Бинарники провайдера | `nubes-terraform-registry` | `////` | ---- +- S3-эндпоинт: `https://s3.msk-1.ngcloud.ru` (Ceph RGW). Клиент `mc` (алиасы `prod-s3`/`reg`/`registry`/`tfreg`). +- Доставка до браузера: S3 → ВМ-зеркало (`/var/www/tf-docs/`) → nginx ВМ отдаёт `//` → под `tf_docs` (reverse-proxy в кластере) → `https://tf-docs.nodejsk8s.dev.nubes.ru//`. +- ВМ отдаёт также по прямому IP `http://5.172.178.213//`. -## Команды (полный цикл, стенд = dev/test/prod) +## Быстрые команды ```bash -# DEV (пример) +# Полный цикл для стенда 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 +./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/dev + +# Только пересборка и публикация (YAML/Go не менялись) +./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/test + +# Ручная заливка уже собранного site/ +scripts/publish-docs.sh site tf-docs.nodejsk8s.dev.nubes.ru nubes-test nubes ``` - -**Быстрая заливка** (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////` | -| **Бинарники провайдера** | `nubes-terraform-registry` | `////` | - -- Эндпоинт 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`).