Decision: How should external_needs find a docs target's local Needs? #899

Decision

Should external_needs keep finding another docs target’s local Needs file by deriving its private target name, or should docs targets publish an explicit reference to that file?

Background

When one docs project imports Needs from another, the build needs to know which generated JSON file to load. Today, external_needs = [":other_docs"] is internally mapped to :other_docs.__internal__.needs_local.

Both ends of this connection are our own rules, and the generated name is private. Users do not need to know it. The practical downside is that an unsupported target can fail with a confusing “missing target” error instead of a clear “this target has no local Needs” message.

✅ Keep the current approach

• Less code and fewer moving parts.
• The private naming rule is controlled by us.
• Errors for unsupported targets are less direct.

🔁 Add an explicit reference (a Bazel “provider”)

A provider is a small piece of information a target publishes about itself. Here it would say: “this docs target’s local Needs file is this one.” A build rule could check that reference before running Sphinx.

Benefits: clearer early errors; the build checks that a target really supplies local Needs.

Costs: extra wrapper rules and steps to pass the file reference through the build and into Sphinx. Avoiding the private-name calculation is mostly internal cleanup, since both ends are maintained here. In the local prototype, the runtime manifest still contains the internal inventory label.

What implementation would involve

The prototype adds the provider in bzl/bundle_rules.bzl, publishes it from wrappers for docs() and docs_bundle() in bzl/needs_rules.bzl, and updates docs.bzl plus the CLI helpers to pass the reference and file through. It changes 5 files (+364/−107 lines); it is uncommitted and has not been tested.

Open question

Are clearer early errors useful enough to justify the extra plumbing? If not, keep the current approach. This issue is for making that decision; implementation can follow only if we choose the provider.

Related: #898 makes the local Needs export available as a JSON file.