tf_provider/docs/help/how-to-docs.md

Как править и публиковать документацию

Полный процесс: от правки .md до появления на сайте.

---

1. Где лежат исходники

Что	Путь
Markdown-файлы документации	docs/
Конфиг MkDocs	mkdocs.yml (корень репо)
Ресурсные страницы (автогенерация)	docs/30_registry/resources/
Гайды	docs/30_registry/guides/
Собранный сайт (не под git)	site/

Какие файлы публикуются

MkDocs собирает только то, что не попало под exclude_docs в mkdocs.yml:

Публикуются: index.md, 30_registry/*, 90_finance/*, ops/*, ARCHITECTURE_NEW/*, TODO/*, и др.

Исключены: README.md, ai_universal_provider_gen.md, 00_overview/*, 20_discovery/*, 40_analysis/*, 50_history/*, 60_strategy/*, 70_api/*, help/*

Если хочешь добавить новую страницу — создай .md в папке, которая НЕ в exclude, и пропиши её в секцию nav: в mkdocs.yml.

---

2. Как править

1. Открываешь нужный .md файл в docs/
2. Редактируешь
3. Если добавил новый файл — добавляешь ссылку в nav: в mkdocs.yml
4. Если менял навигацию — проверь, что все ссылки валидны

---

3. Сборка сайта (MkDocs)

Локально

# если mkdocs установлен в системе
mkdocs build -d site

# или через .venv
.venv/bin/python -m mkdocs build -f mkdocs.yml -d site

Через Docker

docker run --rm -v $(pwd):/docs squidfunk/mkdocs-material build -f /docs/mkdocs.yml -d site

Скриптом (04_build_and_publish_docs.sh)

Скрипт TOOLS/scripts/04_build_and_publish_docs.sh делает всё сразу:

export S3_ENDPOINT=https://s3.msk-1.ngcloud.ru
export S3_ACCESS_KEY=...
export S3_SECRET_KEY=...
./04_build_and_publish_docs.sh 2.0.2

Что он делает под капотом:

1. Берёт версию из provider/main.go (или из аргумента)
2. Создаёт временный mkdocs.yml с подставленным site_url под версию
3. Собирает сайт: пробует Docker → .venv → системный mkdocs
4. Загружает site/ в S3 (вызывает publish-docs.sh)

---

4. Публикация в S3 (Registry)

Скрипт загрузки: /home/naeel/terra/scripts/publish-docs.sh

./scripts/publish-docs.sh <site-dir> <host> <namespace> <name> <version>

Пример:

./scripts/publish-docs.sh site registry.kube5s.ru nubes nubes 2.0.2

Что делает:

• Копирует site/ → s3://terraform-registry/docs/nubes/nubes/2.0.2/
• Выставляет public policy
• Итоговый URL: https://registry.kube5s.ru/docs/nubes/nubes/2.0.2/

S3 credentials (любой из способов):

• Переменные окружения: S3_ENDPOINT, S3_ACCESS_KEY, S3_SECRET_KEY
• Или файл secrets/.s3cfg_registry

---

5. Быстрая публикация одной страницы

Если нужно поправить одну страницу без перезагрузки всего сайта:

./scripts/publish-doc-page.sh \
  --profile devops/profiles/test \
  --version 5.0.17 \
  --page 30_registry/guides/getting-started/index.html

---

6. CI/CD (GitHub Actions)

Файл: .github/workflows/publish-docs.yml

Триггеры:

• Пуш тега v*.*.*
• Ручной запуск (workflow_dispatch)

Что делает:

1. Checkout репозитория
2. Установка Python + mkdocs-material
3. Сборка: mkdocs build -d site
4. Установка mc (MinIO Client)
5. Публикация: ./scripts/publish-docs.sh site <host> <ns> <name> <version>

Secrets (настроить в GitHub):

• S3_ENDPOINT
• S3_ACCESS_KEY
• S3_SECRET_KEY
• REGISTRY_HOSTNAME (опционально, по умолчанию registry.kube5s.ru)

---

7. Быстрый чек-лист

• Открыл .md файл в docs/
• Внёс правки
• Если новый файл — добавил в nav: в mkdocs.yml
• Собрал локально: mkdocs build -d site
• Проверил, что страницы выглядят нормально (открыть site/index.html)
• Опубликовал: ./04_build_and_publish_docs.sh <version>

---

8. Где что лежит (шпаргалка)

Файл	Назначение
mkdocs.yml	Конфиг сайта, навигация, exclude_docs
TOOLS/scripts/04_build_and_publish_docs.sh	Полный пайплайн: сборка + публикация
scripts/publish-doc-page.sh	Публикация одной страницы
/home/naeel/terra/scripts/publish-docs.sh	Скрипт загрузки в S3
.github/workflows/publish-docs.yml	CI/CD авто-публикация по тегу
secrets/.s3cfg_registry	S3 credentials (не под git)