[tobiaskaestner]

Closes #26

Based on main, independent of #35, #36 and the #25 PR. ADR number: this adds ADR 0017 (0015 is #36, 0016 is the #25 PR). 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

An optional per-document imports: list (for kind: sphinx). It names the documents whose needs the document imports. Without the key nothing changes (all-to-all).

stkreq:  {needs: {source: json}, imports: []}
sysreq:  {needs: {source: json}, imports: [stkreq]}
swreq:   {needs: {source: json}, imports: [sysreq]}   # gets sysreq's and stkreq's needs

• Transitive: the imports: of a listed document are followed. An imported need keeps its links, which resolve only if their targets are imported too, so a document lists only its direct upstream documents.
• A listed document without imports: adds only itself. It does not mean "every peer", which would undo the narrowing for all its importers.
• Only needs_external_needs changes. Intersphinx, doxylink, TAGFILES and the navigation stay all-to-all.
• Configure-time validation: a list of ids, each existing, publishing needs, not crossref: false, not the document itself. Only kind: sphinx documents may have the key.
• Docs: registry schema (imports, needs), the registry explanation, consumer contract wording, ADR 0017.

Why

A downstream set that builds upstream documents got all-to-all imports. Each needs warning repeated once per importer, and upstream documents showed the downstream documents' incoming links.

How tested

• Unit: new test_docrefs_imports.py (13 tests) on docrefs.load(). It covers the default, an empty list, direct and transitive imports, a listed document without a list, a cycle, intersphinx unaffected, and every validation error. Full suites: 569 passed (8.3, CI pins).
• 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: check --all passes on this branch (registries unchanged). In a copy of the downstream ee repo's registry I set se-req: [], se-arch: [se-req], ee-joint: [se-arch] and ee-test: [ee-joint]. The strict (-W) ee build passes, so the transitive imports resolve every link (ee-test → ee-joint → se-arch → se-req). The locally built upstream se-req page then shows no downstream "satisfied by" links, the same as in its own repository's build. With all-to-all it showed 2.

Open questions

1. Indirect upstream documents still have to be in the registry. "Resolved without being re-listed downstream" works for the imports (a downstream document lists only its direct upstream). But every upstream document must still be a registry entry, so that it is built and has a needs.json. Reading the imports: (and the entries) of an upstream repository's own documents.yaml, so that a downstream set need not list the indirect upstream documents at all, overlaps with "Import-only" document kind #28 (import-only kind). I left it out. How do you want it shaped?
2. A listed document without imports: adds only itself. If its needs link into a document that is not imported, the importer warns needs.external_link_outgoing. The alternative ("no list = all peers", transitively) is always safe but rarely narrows anything. I chose the explicit variant to match the acceptance criterion "imports only from the documents it lists".
3. imports: also decides which incoming links a document shows. imports: [] on an upstream document gives up the downstream impact view (back-links) in that set. This is documented.

🤖 Generated with Claude Code