# Документация 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`).