mirror of
https://github.com/Vateron-Media/XC_VM.git
synced 2026-09-25 20:01:56 +02:00
Divarion_D
dcd1d8c860
Replace the hand-maintained Docsify site (parallel docs/en + docs/ru trees that had already drifted) with a MkDocs Material build where English is the single source of truth and Russian is generated at build time. Engine & structure - mkdocs.yml: Material theme, site_url for the /XC_VM/ Pages subpath, and a two-tab information architecture — User Guide (administration, API/Swagger, UI translations, diagnostics, info/FAQ) vs Developer Guide (architecture, workflow, security, integrations, build). Files are NOT moved — the split is nav-only, so URLs and cross-links stay stable. - mkdocs-static-i18n (folder mode): English at root, Russian under /ru/, with a language switcher. `mkdocs build --strict` validates every link/anchor. Translation pipeline (tools/docs/translate.py) - Engine-agnostic via DOCS_TRANSLATE_PROVIDER: translators (free, no API key — default), anthropic, deepl, or noop. Per-file sha256 cache so only changed English files are re-translated. Markdown-safe: code, URLs, HTML tags and glossary terms (XC_VM, FFmpeg, HLS, ...) are masked and never translated. A file whose translation fails falls back to English so the build never breaks. - docs/ru is generated and gitignored — never committed. It is produced locally (`make docs-serve` / `docs-build`) and in CI. CI & tooling - pages.yml: build-then-upload (setup-python -> install -> restore .docs-cache with restore-keys -> translate -> mkdocs build --strict -> deploy), replacing the verbatim docs/ upload. - Makefile: docs-venv / docs-translate / docs-build / docs-serve. - docs/requirements.txt; .gitignore for docs/ru, site/, .docs-cache. Migration details - Removed Docsify control files (index.html, _navbar.md, _sidebar.md, .nojekyll) and de-Docsify-ed body links in 6 English files (en-us/ aliases -> relative, swagger _media paths, stripped ':ignore' link syntax). - Preserved the two Russian-only planning docs (no English source) by moving them into docs/adr/ as *.ru.md (repo-internal, excluded from the site).