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