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

> Полный процесс: от правки `.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)

### Локально

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

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

### Через Docker

```bash
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` делает всё сразу:

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

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

Пример:
```bash
./scripts/publish-docs.sh site terra.k8c.ru nubes nubes 2.0.2
```

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

**S3 credentials** (любой из способов):
- Переменные окружения: `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`
- Или файл `secrets/.s3cfg_registry`

---

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

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

```bash
./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` (опционально, по умолчанию `terra.k8c.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) |