[tobiaskaestner]

Closes #25

Based on main, independent of #35 (sphinx-needs 9.2) and #36 (strict mode). ADR number: this adds ADR 0016, because #36 adds 0015 and the #26 PR adds 0017. Each PR adds one line after 0014 in decisions/index.rst, so a trivial conflict there is expected; I can rebase on request.

What changed

version_project now names the repository that dates the document, and version_scope names which of its tags. One function, docrefs.document_version, serves Sphinx documents (zdocs_conf), the Doxygen CLI (docrefs.py version) and the PDF file names (pdf_files):

• With version_project, the repository is that west project (west list, run in ZDOCS_WEST_TOPDIR). Without it, the repository is ZDOCS_PROJECT_BASE, as before.
• version_scope is matched as <scope>/* in that repository and stripped. So an upstream document built downstream with the upstream's scope copied shows the same version as in the upstream's own build.
• version_project without a scope gives the project's nearest tag with the namespace stripped (sysreq/v1.0 → v1.0).
• The v0.0-dev+g<sha> fallback takes the sha of that repository. A project without tags also gets the fallback. Before, --always gave a bare sha, so an untagged upstream document showed acb2519 downstream and v0.0-dev+gacb2519 in its own build.
• Docs: registry schema (version_scope, version_project), ADR 0016, the CLI help.

Why

zdocs_conf.py:185 passed only scope, so Sphinx and Doxygen could show different versions for one repository. An upstream document built through doc_dir: showed the consuming repository's version.

How tested

• Unit: new test_docrefs_version.py (9 tests) on a real west workspace (.west/config and a manifest) with two git repositories. It covers scope alone, project alone (namespace stripped), scope matched in the project, fallbacks, the VERSION override, ZDOCS_WEST_TOPDIR from the environment, CLI == Sphinx path, and an untagged project. Control: without the docrefs.py change, 5 fail. Full suites: 565 passed (8.3, CI pins). One test fake of Refs in test_zdocs_latex.py gained version_project.
• Acceptance (zdocs-tests, 8.3): 238 passed, 11 failed, 20 skipped: the same failure set as main in the same environment (the 11 come from the environment and already fail on main; details in sphinx-needs 9.2; unique prefixes; no group with a document's target name #35).
• zdocs' own docs: build clean, doc-check OK.
• Real consumer (3-repo west workspace, check --all): passes. The upstream requirements document now shows the version of its own repository in every set: v0.0-dev+gacb2519 in its own repo, in the downstream ee repo and in the manifest full set. Before, it showed the ee sha and the manifest sha.

Open questions

1. Behaviour change: a registry that set both keys used to match the scope in the consuming repository and ignore the project. It now matches the scope in the project. I think that is the intended meaning, but it is a change.
2. Per-document repo root from doc_dir's git root (suggested in the issue) is not done. The repository is named in the registry (version_project), not derived. A derived root would change the version of documents in nested repositories or submodules without any registry change. Do you want the derived variant as a default when version_project is absent?
3. The version needs west on PATH and ZDOCS_WEST_TOPDIR at build time. Without them the consuming repository dates the document, as before (no error).

🤖 Generated with Claude Code