docs: дизайн таблиц, ответы Соннета, CSS, правила без ВМ
This commit is contained in:
Naeel
@@ -0,0 +1,155 @@
|
||||
# Как править и публиковать документацию
|
||||
|
||||
> Полный процесс: от правки `.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) |
|
||||
Reference in New Issue
Block a user