[tobiaskaestner]

Closes #34

Independent of the other open PRs for #29, #25 and #26 (all based on main); none of them needs sphinx-needs 9.2.

What changed

1. build: sphinx-needs 9.2.0: the engine pin (sphinx/requirements-doc.txt) and the CI pins (doc/requirements-ci.txt) move from 8.3.0 to 9.2.0. 9.2 needs two new packages, ub-needs-exchange==1.1.0 and ub-project==1.2.0 (added to the CI pins). All other CI pins are inside 9.2's ranges and stay as they are (pip install --dry-run -r doc/requirements-ci.txt resolves with only these three changes).
   • One control test pinned the 8.3 defect behind needs_config_state: a new link type in the TOML crashed an incremental build. 9.2 re-reads the document itself (config changed ('needs_links')), so that control now pins the 9.2 behaviour. A removed link type still crashes an importing document without the extension, so a second control pins that case and the extension stays. Docstrings, zdocs_conf and the consumer contract now describe it that way.
2. feat: docrefs: unique prefixes, and no group with a document's target name: two configure-time checks in docrefs._validate, with messages that name the documents:
   • Prefixes are unique per link map: two sphinx/sphinx-external documents (intersphinx_mapping) or two doxygen/doxygen-external documents (doxylink) with the same prefix. The default prefix counts too (my-doc and my_doc clash). A Sphinx and a Doxygen document may still share a prefix, because they key different maps and different roles. external and crossref: false documents are in no map.
   • Group vs. document targets: a group whose <group>-<builder> aggregate has the same name as a document's own target (the manual/manual-html case from doc/documents.yaml). Before this, CMake stopped with a duplicate-target error that did not name the registry.
   • Docs: registry schema (prefix, group id), the registry explanation, and the comment in doc/documents.yaml.

Why

#34: the pin has been run against 9.2 without problems, and 9.2 adds per-type schema rules, a status enum and hash fields. Both mistakes above were documented as "not validated" and only failed later, if at all.

How tested

• Unit suites (sphinx-needs 9.2.0, Sphinx 9.1.0, Python 3.14): 568 passed. New test_docrefs_consistency.py (11 tests). Control: without the docrefs.py change, its 6 reject tests fail.
• Acceptance (zdocs-tests) against this branch with 9.2: 238 passed, 11 failed, 20 skipped. That is the same failure set as main with 8.3 in the same environment, so the bump adds no regression. The 11 failures come from the environment and are already there on main: no LaTeX toolchain (latexmk stub), no SSH, the suite's own topology/test-manifest checks, and absolute-base_url link assertions that predate ADR 0012. Run in a west workspace built for the suite under build/ (zdocs as a worktree at tools/zdocs, a 13 MB Zephyr subset). I added the fixture tags widget/v2.3, handbook/v1.4 and duties/v0.9 locally; duties/v0.9 is not in the README's list.
• zdocs' own docs (doc/) build with 9.2: doc-check OK, empty stage-2 logs.
• Real consumer: a 3-repo west workspace (syseng, ee, manifest full set; strict build -W, sphinx-needs schemas) passes check --all against this branch.

Open question

• The validation is strict only where a real clash exists (same map, same builder). Should prefixes rather be unique across the whole set, Sphinx and Doxygen alike? That would be simpler to explain, but a registry that works today could stop configuring.

🤖 Generated with Claude Code