docs: commit generated ru, translate locally before release (not in CI)

CI translation was slow, so move it out of GitHub Actions: docs/ru is now a
committed, generated tree refreshed LOCALLY before a release; CI only builds it.

- pages.yml: drop the setup-python/cache/translate steps — the workflow now just
  installs the build toolchain and runs `mkdocs build --strict` on the committed
  en+ru trees.
- .gitignore: stop ignoring docs/ru (now committed); keep site/ + .docs-cache/.
- Split deps: docs/requirements.txt = build only (mkdocs-material, static-i18n,
  used by CI); tools/docs/requirements.txt = translators (local-only).
- Makefile: docs-venv installs both; docs-build/docs-serve no longer translate
  (translation is the deliberate `make docs-translate` release step).
- updates_checklist.md: new "Regenerate translated documentation" step
  (make docs-translate + docs-build, commit docs/ru with the release commit).
- Commit the generated docs/ru (37 files, translators/yandex).

Rule: edit ONLY docs/en; docs/ru is generated — never hand-edit it.
This commit is contained in:
Divarion_D
2026-08-20 22:37:44 +03:00
parent c55238f85b
commit bdbcde97c7
45 changed files with 8391 additions and 64 deletions
+5 -29
View File
@@ -1,16 +1,16 @@
name: Deploy docs to Pages
# Builds the MkDocs (Material) site and publishes it to GitHub Pages. English
# (docs/en) is the single source; Russian (docs/ru) is generated at build time
# by tools/docs/translate.py and is NOT committed. Runs only when docs actually
# change, unlike GitHub's built-in "pages build and deployment".
# (docs/en) is the single source you edit; Russian (docs/ru) is a GENERATED tree
# that is committed and refreshed LOCALLY before a release (`make docs-translate`)
# — translation is intentionally NOT run in CI (it is slow). CI only builds the
# already-translated site. Runs only when docs actually change.
on:
push:
branches: [main]
paths:
- 'docs/**'
- 'mkdocs.yml'
- 'tools/docs/**'
- '.github/workflows/pages.yml'
workflow_dispatch:
@@ -40,33 +40,9 @@ jobs:
with:
python-version: '3.12'
- name: Install docs toolchain
- name: Install docs build toolchain
run: pip install -r docs/requirements.txt
# Per-file translation cache: only English files that changed since the
# last run hit the translation backend. The exact key misses whenever any
# docs/en file changes; restore-keys then pulls the most recent prior
# cache so translate.py can diff against it and re-translate just the delta.
- name: Restore translation cache
uses: actions/cache@v4
with:
path: .docs-cache
key: docs-tr-${{ hashFiles('docs/en/**', 'tools/docs/**') }}
restore-keys: |
docs-tr-
# Defaults to `translators` — free web engines, NO API key. A file whose
# translation fails (rate-limit/outage) gracefully falls back to English
# so the deploy never breaks, and is retried next run. Override with the
# DOCS_TRANSLATE_PROVIDER repo variable (+ the matching key secret) to use
# anthropic/deepl.
- name: Generate translated docs (ru)
env:
DOCS_TRANSLATE_PROVIDER: ${{ vars.DOCS_TRANSLATE_PROVIDER || 'translators' }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
DEEPL_AUTH_KEY: ${{ secrets.DEEPL_AUTH_KEY }}
run: python tools/docs/translate.py --lang ru
- name: Build site (strict)
run: mkdocs build --strict