Skip to content

documentation.md

Latest commit

 

History

History
85 lines (57 loc) · 3.79 KB

documentation.md

File metadata and controls

85 lines (57 loc) · 3.79 KB

Documentation guide — BirdLense Hub

How docs are organized for contributors and readers.

Русский (legacy; новые страницы — docs/ru/*.ru.md, гайд — эта страница EN).

Layout (2026)

Path Audience MkDocs
docs/user/ Operators (install, config, deploy, runbooks) Yes — User Guide
docs/contributor/ Developers (architecture, API, CI, security) Yes — Contributor Guide
docs/ru/ Russian (*.ru.md) Yes — Русский
docs/index.md Doc home / cross-links Yes — Home
archive/internal/docs-legacy/ ML deep-dives, old flat names, checklists No (repo-only)
Repo root README*, CONTRIBUTING*, SECURITY*, release-readiness.md Linked from index

Rule: new maintained pages go under user/, contributor/, or ru/ — not as docs/FOO.md at the top level.

Adding a published page

  1. Add the Markdown file under the correct subtree.
  2. Register it in root mkdocs.yml nav (English and/or Русский).
  3. Update docs/index.md or the section index (user/index.md, contributor/index.md, ru/index.md).
  4. Add a row to docs/_meta/docs_inventory.csv.
  5. Cross-link from related pages; keep EN + RU pairs in sync when both exist.

Static site (MkDocs + GitHub Pages)

  • Config: root mkdocs.yml, docs_dir: docs.
  • App Python 3.11 vs MkDocs Python 3.12 — use .venv-docs (requirements-docs.txt), not the app container.
  • Local: python3 -m venv .venv-docs && .venv-docs/bin/pip install -r requirements-docs.txt && .venv-docs/bin/mkdocs serve
  • CI / release: make ci-local runs mkdocs build --strict via .venv-docs.
  • Version banner: root VERSION must match mkdocs.yml extra.site_version (scripts/check-docs-version.py).

Excluded from the site (exclude_docs in mkdocs.yml): archive/**, generated docs/api/**, docs/ui/**, and flat-name redirect stubs at docs/INSTALL.md, docs/CONFIGURATION.ru.md, etc. (generated by scripts/generate-doc-redirect-stubs.py).

Legacy URLs on GitHub Pages: mkdocs-redirects maps old flat names (e.g. INSTALL.md) to user/install.md. Regenerate stubs + redirect map after adding pages:

python3 scripts/generate-doc-redirect-stubs.py
python3 scripts/generate-doc-redirect-stubs.py --fix-changelog --no-stubs

SITE_MAP guard: scripts/check_site_map_meta_paths.py skips when docs/SITE_MAP.md is absent or a redirect stub (legacy maps live under archive/internal/docs-legacy/).

Language policy

  • English is primary for new pages in docs/user/ and docs/contributor/.
  • Russian uses docs/ru/<name>.ru.md with a link to EN at the top when a pair exists.
  • Cross-links: prefer the same language; link to EN contributor pages when no RU file exists (e.g. roadmap.md, ci-and-quality.md).

Security in examples

Use placeholders: YOUR_HOST, your-token, 203.0.113.10 (TEST-NET-3) — never production secrets or private IPs from deploy configs.

Reviewer checklist (doc PRs)

  • EN updated; *.ru.md updated when behavior or nav changes.
  • No new top-level docs/LEGACY_NAME.md without a migration plan.
  • Links use user/, contributor/, or ru/ paths (or explicit archive/internal/docs-legacy/ for archived SSOT).
  • mkdocs.yml nav includes new public pages.
  • docs/_meta/docs_inventory.csv row added.
  • OpenAPI bulk regen (if any): python3 scripts/merge_openapi_fragments.py + contract tests.

See also