# Документация провайдера Nubes: генерация и публикация

> Актуально на 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/<namespace>/<name>/   (без версии, public)
                                                        │
                                                        ▼
                       ВМ 5.172.178.213 nginx (зеркало /var/www/tf-docs/) ◀─ под tf_docs (proxy)
                                                        │
                                                        ▼
                        https://tf-docs.nodejsk8s.dev.nubes.ru/<namespace>/
```

Ключевые принципы:
- **Без версий в URL**: docs публикуются в `docs/<namespace>/<name>/` перезаписью (`mc mirror --overwrite --remove`).
- **Вечный бесплатный домен**: `tf-docs.nodejsk8s.dev.nubes.ru/<namespace>/` (managed-кластер → под-прокси → ВМ nginx).
- Имя провайдера (`<name>`) во всех стендах — `nubes`; в URL сайта не фигурирует (только `<namespace>`), в S3-ключе — есть.

## Стенды

| Стенд | 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 ... <ver>` | сборка провайдера + GPG-подпись + бинарники в S3 (не docs) |

## Поток B — сборка MkDocs-сайта и публикация

| Шаг | Скрипт | Что делает |
|---|---|---|
| 1 | `TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/<стенд> [ver]` | собирает сайт и публикует (см. ниже) |
| 2 | `scripts/publish-docs.sh <site> <host> <ns> <name>` | заливка `site/` в S3 (см. ниже) |
| 3 (опц.) | `scripts/publish-doc-page.sh` | заливка одной страницы |
| CI | `.github/workflows/publish-docs.yml` | авто-публикация по git-тегу `v*.*.*` |

### Детали шага 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://<REGISTRY_HOST>/<NAMESPACE>/`;
   - `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 <endpoint> <ak> <sk> --api S3v4`.
- `mc mirror --overwrite --remove "$SITE_DIR/" → registry/terraform-registry/docs/<namespace>/<name>/`.
- `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 и хостинг

| Что | Бакет | Ключ |
|---|---|---|
| Документация | `terraform-registry` (public) | `docs/<namespace>/<name>/` — без версии |
| Бинарники провайдера | `nubes-terraform-registry` | `<host>/<namespace>/<name>/<version>/` |

- S3-эндпоинт: `https://s3.msk-1.ngcloud.ru` (Ceph RGW). Клиент `mc` (алиасы `prod-s3`/`reg`/`registry`/`tfreg`).
- Доставка до браузера: S3 → ВМ-зеркало (`/var/www/tf-docs/`) → nginx ВМ отдаёт `/<namespace>/` → под `tf_docs` (reverse-proxy в кластере) → `https://tf-docs.nodejsk8s.dev.nubes.ru/<namespace>/`.
- ВМ отдаёт также по прямому IP `http://5.172.178.213/<namespace>/`.

## Быстрые команды

```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/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
```