tf_provider/DOCS_PIPELINE

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

# 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:

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

Ручная заливка доков (рабочий способ)

# 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

Варианты устранения (только после «делай»)

1. Восстановить scripts/publish-docs.sh в это репозиторий (из копии рядом или из git c2438f5^).
2. Инлайнить заливку прямо в 04_build_and_publish_docs.sh (как уже сделано в publish-doc-page.sh).