Писане на документация

Правилото

Всяка промяна в кода обновява тази документация в entrosity-docs, качена заедно с промяната в кода. Една промяна не е завършена, докато документацията не я описва.

Ако промените…	Обновете
Страница на портала, формуляр, етикет или работен процес	Страницата в `user-guide/` или `administration/`
Роля или правило за достъп (`rbac`, `portal/access.go`)	Роли и права
`api/openapi.yaml` на бекенд	Нищо за справочника на крайните точки (той се генерира от `specs/` и се опреснява автоматично); обновете API на портала или API на Hub, ако конвенциите се променят
Код на грешка (`apperr.New`, кодове на задачи или на push)	Кодове на грешки
Променлива `RMM_` или `PLATFORM_` или настройки на compose	Конфигурация (и Инсталиране за `.env` в продукция)
Миграция	Модел на данните, включително таблицата с миграциите
Съобщение от протокола, тип задача или payload (`entrosity-shared-go/proto`)	Протокол, Агент или Конектор
CLI на агента или конектора, MSI свойства, файлове	Агент, Конектор
Скриптове за разгръщане, работни потоци, наблюдение (`entrosity-infra`)	Страницата в `operations/` и CI работни потоци
Страница, формуляр, етикет или работен процес на Entrosity Edge (`entrosity-edge.frontend`)	Страницата в `edge/`
Роля, код на грешка, променлива `EDGE_*`, миграция или срок за съхранение на Edge (`entrosity-edge.backend`)	Роли в Edge, Кодове на грешки, Работа с Entrosity Edge
Съобщение, задача или payload на протокола на Edge (`entrosity-shared-go/proto/edge`), CLI, MSI или симулаторът на конектора на Edge	Протокол на конектора на Edge, Конектор на Edge, Изпробване на Edge със симулатора
Роля, правило за достъп, код на грешка, променлива `SPHERE_*`, миграция, задача или срок за съхранение на Sphere (`entrosity-sphere.backend`) или настройките на медийния му сървър (`deploy/mediamtx.yml` в `entrosity-infra`)	Роли в Sphere, Кодове на грешки, Работа с Entrosity Sphere
Съобщение, задача или payload на протокола на Sphere (`entrosity-shared-go/proto/sphere`), CLI, MSI, драйвери или симулаторът на конектора на Sphere	Протокол на конектора на Sphere, Конектор на Sphere, Изпробване на Sphere със симулатора
Страница, формуляр, етикет или работен процес на Entrosity Matrix (`entrosity-matrix.frontend`)	Страницата в `matrix/`
Роля, правило за достъп, код на грешка, променлива `MATRIX_*`, миграция, задача, срок за съхранение или командата `import-stop-internet` на Matrix (`entrosity-matrix.backend`), или разгръщането му (`entrosity-infra`, compose профил `matrix`)	Роли в Matrix, Кодове на грешки, Работа с Entrosity Matrix
Съобщение, задача, payload или правило за разрешаване на протокола на Matrix (`entrosity-shared-go/proto/matrix`), CLI, локалната защита, проверката, MSI или симулаторът на конектора на Matrix	Протокол на конектора на Matrix, Конектор на Matrix, Изпробване на Matrix със симулатора
Роля, правило за достъп, код на грешка, променлива `VERTEX_`, миграция или срок на съхранение на Vertex (`entrosity-vertex.backend`), или частта на Axis за Vertex (`RMM_VERTEX_`, `RMM_INTERNAL_ADDR`, препредаването)	Роли във Vertex, Отстраняване на проблеми с Vertex, Работа с Entrosity Vertex
Съобщение, операция или payload на протокола на Vertex (`entrosity-shared-go/proto/vertex`), или скриптът, защитата или CLI `vertex guard` на конектора за Vertex	Протокол на Vertex, Локалната защита на конектора, Конектор за обекта
Make цел	Make цели
Хранилище или начина, по който хранилищата зависят едно от друго	Хранилища
Всичко, видимо за потребителя	`CHANGELOG.md` в това хранилище (страницата Дневник на промените се генерира от него)
Която и да е страница в `docs/`	Нейното българско копие в `i18n/bg/` (вижте Преводи)

CLAUDE.md на всяко хранилище съдържа същото правило за промени, направени с помощта на AI.

Сайтът

Хранилище: entrosity-docs (Docusaurus 3, конфигурация на TypeScript).
Съдържание: docs/**/*.md. Ред в страничната лента: sidebars.ts (всяка страница трябва да бъде изброена там).
Справочниците за API на /api-reference (Axis), /hub-api-reference (Hub), /edge-api-reference (Edge), /sphere-api-reference (Sphere), /matrix-api-reference (Matrix) и /vertex-api-reference (Vertex) се генерират от Redocusaurus от specs/axis-openapi.yaml, specs/hub-openapi.yaml, specs/edge-openapi.yaml, specs/sphere-openapi.yaml, specs/matrix-openapi.yaml и specs/vertex-openapi.yaml — моментни снимки на api/openapi.yaml на бекендите. pnpm fetch:specs [ref] ги опреснява; работният поток openapi-updated.yml прави това, когато бекенд промени спецификацията си в main.
Страницата с дневника на промените се генерира от CHANGELOG.md от scripts/sync-changelog.mjs преди start и build; не редактирайте docs/changelog.md (той е игнориран от git).
Диаграмите са Mermaid блокове с код (```mermaid).
Търсенето е локално (@easyops-cn/docusaurus-search-local); индексът се изгражда от pnpm build, така че търсенето работи в изградения сайт, а не в pnpm start.

pnpm install
pnpm start    # http://localhost:3000 with live reload
pnpm build    # fails on broken links and anchors
pnpm serve    # serve the built site

Преводи

Сайтът се публикува на английски (по подразбиране, в корена) и на български (под /bg/). Читателите превключват от менюто за език в навигационната лента.

Какво	Английски	Български
Страници	`docs/*/.md`	`i18n/bg/docusaurus-plugin-content-docs/current/*/.md`, същите пътища
Етикети на категориите в страничната лента	`sidebars.ts`	`i18n/bg/docusaurus-plugin-content-docs/current.json`
Навигационна лента и долен колонтитул	`docusaurus.config.ts`	`i18n/bg/docusaurus-theme-classic/navbar.json`, `footer.json`
Низове на темата и търсенето	вградени	`i18n/bg/code.json`

Английският е изходният език. Първо променете английската страница, а след това нейното българско копие в същия къмит. Страница без българско копие се показва на английски в българския сайт.
Заглавията в българските страници носят английската котва като изричен ID (## Инсталиране {#installation}), така че връзките и котвите са еднакви и на двата езика. pnpm i18n:scaffold docs/<page>.md копира нова английска страница в i18n/bg/ с тези ID, готова за превод. pnpm i18n:check отчита страници без българско копие и заглавия, чиито ID се различават между двете версии.
Запазвайте имената на елементите от UI на английски, точно както ги показва порталът (порталът е само на английски). Код, пътища, променливи, кодове и имена в API никога не се превеждат.
Изключение са Entrosity Edge и Entrosity Matrix: приложенията им са преведени, затова българските страници в edge/ и matrix/ назовават елементите от UI с българските етикети на самото приложение (съобщенията bg в entrosity-edge.frontend/src/**/messages.ts и entrosity-matrix.frontend/src/**/messages.ts).
Дневникът на промените е само на английски; българският сайт показва същата страница под преведено заглавие.
Нови етикети в sidebars.ts или docusaurus.config.ts: pnpm docusaurus write-translations --locale bg ги добавя в JSON файловете (съществуващите преводи се запазват); преведете новите записи.
pnpm start обслужва един език наведнъж; pnpm start --locale bg обслужва българския сайт. pnpm build изгражда и двата.

Публикуване

Сайтът се обслужва на https://hub.entrosity.com/docs/ от Caddy в уеб образа.

ci.yml на това хранилище изгражда сайта с DOCS_BASE_URL=/docs/, в main качва статичния образ ghcr.io/entrosity/docs:main и изпраща deploy към entrosity-infra, чийто работен поток deploy изгражда наново уеб образа и го разгръща (Непрекъснато разгръщане): deploy/Dockerfile.web копира сайта в /srv/docs, а deploy/Caddyfile обслужва /docs/* със собствена Content-Security-Policy (политиката на портала забранява вградените скриптове, от които Docusaurus се нуждае).

Локално сайтът работи в корена (http://localhost:3000/). DOCS_URL (по подразбиране https://hub.entrosity.com) и DOCS_BASE_URL (по подразбиране /) променят публикувания адрес. DOCS_LINK_CHECK=warn понижава счупените връзки до предупреждения.

Стил

Пишете за читателя на съответния раздел: ориентирано към задачата в ръководството за потребителя, точно и пълно в справочника.
Файловете .md са обикновен CommonMark (фигурните и ъгловите скоби са безопасни). Използвайте .mdx само за страници, които се нуждаят от React компоненти.
Назовавайте елементите от UI точно както ги показва порталът, с удебелен шрифт.
Поставяйте код, пътища, променливи и кодове в обратни апострофи. Посочвайте хранилището, когато даден път не е в това (entrosity-axis.backend/internal/...).
Използвайте admonitions (:::note, :::tip, :::warning, :::danger) за това, което читателите не трябва да пропуснат.
Свързвайте страниците помежду им с относителни .md пътища, така че изграждането да ги проверява.
Проверявайте фактите спрямо кода, а не спрямо по-стари документи.

Инженерни записи

engineering/ в това хранилище съдържа плана за имплементация, плановете по фази, контролните списъци на пътната карта и докладите за производителност. Те са записи за това как е изграден продуктът; този сайт е документацията за това какво представлява той.

Правилото​

Сайтът​

Преводи​

Публикуване​

Стил​

Инженерни записи​