Zimin A.N.
d5268b9395
Новая документация-as-code на платформе Diplodoc (Yandex open-source) с YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно. Что добавлено: - package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar - index.md — главная страница с tabs для разных audiences - README.md — инструкция для contributors Раздел integration/api/ — 11 страниц про интеграцию consumers: - index — обзор + глоссарий - auth — Keycloak service accounts, scope mapping - read-endpoints — GET /dictionaries, list/by-key, spatial filters - events — Kafka outbox топики, partition keys, idempotency, DLQ - webhooks — HMAC, SSRF guard, retry policy, test ping endpoint - bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export - x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview - caching — TTL / push / snapshot strategies, hybrid pattern - errors — full error code reference (validation/auth/conflict/server), retry strategy - best-practices — 33 numbered rules для consumers - bundle-cuod — все 40 справочников с FK графом и сценариями Обновлены: - ops/README.md — link на новую integration/api/, убран inline <br> - ops/slo.md — broken cross-repo links заменены на text references Build: cd docs && pnpm install && pnpm build → ./_dist (20 HTML files, 7.1M) pnpm serve # → http://localhost:8088 CI deploy job для GitLab Pages — в roadmap (см. docs/README.md). Существующий tech/api-integration.md оставлен в toc как legacy (содержимое мигрировано + расширено в integration/api/).
110 lines
3.5 KiB
Markdown
110 lines
3.5 KiB
Markdown
# Ordinis docs (Diplodoc / YFM)
|
||
|
||
Документация Ordinis НСИ ЦУОД ОДХ построена через **Diplodoc** (open-source
|
||
documentation platform от Yandex). Markdown source — YFM (Yandex Flavored
|
||
Markdown) с расширениями для tabs, notes, includes, mermaid диаграмм.
|
||
|
||
## Структура
|
||
|
||
```
|
||
docs/
|
||
├── package.json # @diplodoc/cli + scripts
|
||
├── .yfm # Diplodoc config (langs, plugins)
|
||
├── toc.yaml # Содержание / навигация (рендерится в sidebar)
|
||
├── index.md # Главная страница
|
||
├── integration/ # Интеграция по API
|
||
│ ├── api/ # Главы для consumers
|
||
│ │ ├── index.md # Обзор
|
||
│ │ ├── auth.md # Keycloak / JWT
|
||
│ │ ├── read-endpoints.md
|
||
│ │ ├── events.md # Kafka outbox
|
||
│ │ ├── webhooks.md
|
||
│ │ ├── bitemporal.md
|
||
│ │ ├── x-references.md
|
||
│ │ ├── caching.md
|
||
│ │ ├── errors.md
|
||
│ │ ├── best-practices.md
|
||
│ │ └── bundle-cuod.md
|
||
│ └── altum-imaging-order.md # Прикладной сценарий
|
||
├── ops/ # Operator runbook
|
||
│ ├── README.md
|
||
│ ├── slo.md
|
||
│ ├── outbox-dlq.md
|
||
│ ├── db-migrations.md
|
||
│ ├── vault-unseal.md
|
||
│ └── kafka-restart.md
|
||
├── status/ # State snapshots (исключено из build)
|
||
│ └── *-state.md
|
||
└── tech/ # Legacy технические страницы
|
||
└── api-integration.md
|
||
```
|
||
|
||
## Сборка
|
||
|
||
Требуется Node 18+.
|
||
|
||
```bash
|
||
cd docs
|
||
pnpm install
|
||
pnpm build # → ./_dist (HTML)
|
||
pnpm serve # → http://localhost:8088
|
||
# либо одной командой:
|
||
pnpm dev
|
||
```
|
||
|
||
Build output (`_dist/`) — статический HTML, можно деплоить в:
|
||
- GitLab Pages
|
||
- S3 + CloudFront
|
||
- nginx/ingress на cluster.142
|
||
|
||
## Автор содержимого
|
||
|
||
| Раздел | Owner |
|
||
|---|---|
|
||
| `/` (index, integration/api/*) | zimin.an@nstart.space |
|
||
| `ops/*` | on-call rotation team |
|
||
| `integration/altum-imaging-order.md` | Альтум team contact |
|
||
|
||
## Что не committable
|
||
|
||
- `_dist/` — build output (gitignore'нут)
|
||
- `node_modules/` — dependencies (gitignore'нут)
|
||
|
||
## Deployment
|
||
|
||
В roadmap — GitLab CI job `build-docs`:
|
||
|
||
```yaml
|
||
build-docs:
|
||
stage: build
|
||
image: node:18
|
||
script:
|
||
- cd docs
|
||
- pnpm install --frozen-lockfile
|
||
- pnpm build
|
||
artifacts:
|
||
paths: [docs/_dist]
|
||
expire_in: 1 week
|
||
rules:
|
||
- changes: ["docs/**/*"]
|
||
```
|
||
|
||
Затем deploy в GitLab Pages либо как отдельный k8s deployment с nginx.
|
||
|
||
## YFM extensions используются
|
||
|
||
- `{% list tabs %}` — табы для switching между audiences
|
||
- `{% note info|warning|tip %}` — выделенные блоки
|
||
- `mermaid` code blocks — диаграммы (graph LR, gantt)
|
||
- Cross-links в `toc.yaml` — sidebar navigation
|
||
- `varsPreset: external` — для shared includes (TBD when нужно)
|
||
|
||
## Roadmap
|
||
|
||
- [ ] CI job `build-docs` в `.gitlab-ci.yml`
|
||
- [ ] GitLab Pages deployment
|
||
- [ ] Search через Diplodoc search plugin
|
||
- [ ] EN translation (i18n via `langs:` в `.yfm`)
|
||
- [ ] Includes для shared snippets (auth examples, error tables)
|
||
- [ ] Versioning — separate doc trees per Ordinis major version
|