156 lines
6.0 KiB
Markdown
156 lines
6.0 KiB
Markdown
# Как править и публиковать документацию
|
||
|
||
> Полный процесс: от правки `.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 registry.kube5s.ru <!-- ⛔ LEGACY: registry.kube5s.ru ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.ru --> <!-- ⛔ LEGACY: registry.kube5s.ru <!-- ⛔ LEGACY: registry.kube5s.ru ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.ru --> ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.ru --> nubes nubes 2.0.2
|
||
```
|
||
|
||
Что делает:
|
||
- Копирует `site/` → `s3://terraform-registry/docs/nubes/nubes/2.0.2/`
|
||
- Выставляет public policy
|
||
- Итоговый URL: `https://registry.kube5s.ru <!-- ⛔ LEGACY: registry.kube5s.ru ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.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` (опционально, по умолчанию `registry.kube5s.ru <!-- ⛔ LEGACY: registry.kube5s.ru ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.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) |
|