Files

T

Zimin A.N. d5268b9395 docs: Diplodoc setup + полное руководство интеграции по API

Новая документация-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/).

2026-05-07 23:19:02 +03:00

3.5 KiB

Raw Blame History

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+.

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:

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

3.5 KiB Raw Blame History Unescape Escape