# 2026-09-03 — Проверенный pipeline публикации документации

## Цель

Зафиксировать фактический pipeline публикации заново сгенерированной документации провайдера, чтобы не восстанавливать его заново по догадкам.

## Источник документации

Для стенда `<stand>` используются только сгенерированные страницы:

```text
generated/<stand>/docs/
```

Для DEV:

```text
generated/dev/docs/
```

Ручной каталог `docs/` не используется как основной `docs_dir`. Скрипт `04_build_and_publish_docs.sh` перед сборкой копирует в сгенерированный каталог только общие материалы:

```text
docs/30_registry/
docs/curated/
```

После копирования в `30_registry/guides/getting-started.md` подставляются параметры конкретного стенда:

- namespace;
- версия провайдера;
- API endpoint.

## Актуальные скрипты

Генерация Markdown выполняется так:

```text
TOOLS/scripts/01_generate_yamls.sh
  -> generated/<stand>/resources_yaml/

TOOLS/scripts/02_generate_resources_and_docs_v2.sh
  -> generated/<stand>/docs/
```

Сборка сайта выполняется скриптом:

```text
TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/<stand>
```

Он создаёт временный `.mkdocs.tmp.yml`, задаёт `site_url` с namespace стенда, запускает MkDocs и создаёт:

```text
site/
```

В конце этот скрипт вызывает актуальный:

```text
./scripts/publish-docs.sh site "$REGISTRY_HOST" "$NAMESPACE" "$PROVIDER_NAME" "$VERSION"
```

## Фактическое хранилище документации

Документация хранится не в bucket бинарников провайдера. Используется отдельный bucket:

```text
terraform-registry
```

Публикация выполняется без версии. Для DEV целевой S3 prefix:

```text
terraform-registry/docs/nubes-dev/nubes/
```

Для остальных стендов:

```text
terraform-registry/docs/nubes-test/nubes/
terraform-registry/docs/nubes/nubes/
```

Актуальный `scripts/publish-docs.sh` использует:

```text
mc mirror --overwrite --remove site/ registry/terraform-registry/docs/<namespace>/nubes/
```

Следствие: в URL документации нет версии `2.0.0`, `3.0.0` или `1.0.0`.

## Где выполнять S3 upload

История commit `9e02b69` зафиксировала, что из локальной сети большие рекурсивные операции S3 нестабильны. Поэтому `mc mirror` для документации выполняется на ВМ:

```text
5.172.178.213
```

Проверенный порядок:

```text
1. Собрать site/ локально.
2. Передать site/ на ВМ в ~/tmp-docs-site/.
3. На ВМ выполнить:
   mc mirror --overwrite --remove \
     ~/tmp-docs-site/ \
     registry/terraform-registry/docs/<namespace>/nubes/
4. На ВМ обновить локальное зеркало:
   mc mirror --overwrite --remove \
     registry/terraform-registry/docs/<namespace>/nubes/ \
     /var/www/tf-docs/<namespace>/
```

S3 upload и обновление зеркала — два отдельных действия. Одной загрузки в S3 недостаточно, если публичный proxy читает локальное зеркало ВМ.

## Публичная доставка

На ВМ nginx использует корень:

```text
/var/www/tf-docs/
```

Сервис `tf_docs` проксирует публичный домен на ВМ. Для DEV итоговый путь:

```text
/var/www/tf-docs/nubes-dev/
```

Итоговый URL DEV:

```text
https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-dev/
```

Путь с версией не используется:

```text
https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-dev/2.0.0/
```

не является корректным URL документации.

## Важное различие с публикацией бинарников

Бинарники Terraform-провайдера публикуются в другом bucket и с версионным prefix:

```text
nubes-terraform-registry/
  tf-registry.containerk8s.services.ngcloud.ru/
    <namespace>/nubes/<version>/
```

Документация публикуется отдельно:

```text
terraform-registry/docs/<namespace>/nubes/
```

Не смешивать эти два pipeline.

## Legacy, который не использовать

```text
DOCS_PIPELINE/publish-docs.sh
```

Это справочная legacy-копия старого скрипта. Она использует старую схему `mc cp`, старую структуру и версионный путь. Для текущей публикации использовать:

```text
scripts/publish-docs.sh
```

## История изменений, подтверждающая схему

- `dc469c6` — публикация docs без версии, `mc mirror`, `site_url` по стенду.
- `72a8a49` — актуализация README и новый docs host; старый скрипт помечен legacy.
- `9e02b69` — зафиксирована загрузка S3 с ВМ и обновление зеркала `/var/www/tf-docs/`.
- `02b7d7b` — подстановка namespace, версии и API endpoint выполняется после копирования `30_registry` в стендовый generated docs каталог.