[AlexanderLanin]

Why

A bundle can own a Need that links to one owned by another documentation source. When built by itself, Sphinx-Needs sees only the bundle's local inventory and reports the link as unresolved. Sharing root_docs gives the bundle project settings; it does not make another source's Needs visible. Authors need an explicit way to validate these links without importing the other source's pages or copying its Needs into the bundle's own export.

What changes

• Add external_needs to docs_bundle(). Authors can name a public docs() target or a named docs_bundle() target. docs() accepts those public names too, while continuing to accept legacy needs_json and needs_json_file labels.
• Build each declared source's locally owned Needs inventory as an input to the consumer's standalone Needs build. Sphinx-Needs can resolve links against those records, while the consumer's JSON output remains limited to its own Needs.
• Keep imported inventories' canonical project URLs so external links point to the published documentation. Warn when inventories with the same base URL define the same Need ID, which Sphinx-Needs can otherwise treat as a reload and silently replace.
• Update the macro reference and how-to documentation. The integration scenario covers declared and missing imports, owner-only output, and duplicate IDs across two otherwise valid bundles.

Example

A parent project owns PARENT-123. A component owns CHILD-456 and links it to PARENT-123. Built alone, the component cannot resolve that link. It lists the parent project in external_needs, so Bazel supplies the parent's locally owned Needs inventory for Sphinx-Needs' link check. The link resolves, but the parent's Need is not copied into the component's own Needs JSON, and the parent's pages are not mounted into the component.

The declaration is explicit: without the external_needs entry, the link remains unresolved.

🚨 Impact Analysis

• This change does not violate any tool requirements and is covered by existing tool requirements
• This change does not violate any design decisions
• Otherwise I have created a ticket for new tool qualification

✅ Checklist

• Added/updated documentation for new or changed features
• Added/updated tests to cover the changes
• Followed project coding standards and guidelines

[github-actions]

Documentation preview for this pull request is available at:
pr-890: https://eclipse-score.github.io/docs-as-code/pr-890/

[AlexanderLanin]

open point: docs_bundle(upward_bundles=...) is basically the same as docs(external_needs=...). Two names for the same approach.

---

external_needs includes "the entire thing" while upward_bundles includes only the local needs

---

latest idea is to treat external dependencies as "the entire thing" and local dependencies as "local needs only". Since making both parameters available will be too complex for users.

[AlexanderLanin]

Following up on my API-shape note: I’d like upward_bundles to include each declared bundle’s full composed Needs inventory, including its child bundles, while keeping the dependency graph acyclic.

For docs authors, upward_bundles and external_needs should behave the same. The implementation can handle whether a dependency is local or external internally, without asking authors to choose between different semantics.

[Copilot]

Copilot review overview

🟡 Changes recommended

Root owner-only exports do not receive declared external inventories, and public label resolution has an ambiguous docs target case.

Review effort: Balanced
Findings: 2 · 1

Open (3)

• Avoid conflating docs() with a standalone docs bundle · New
• Forward external needs labels to the root local action · New
• Synchronize Java configuration with PlantUML setup documentation · New

What changed in this PR

Adds explicit external Needs imports for standalone bundle validation while preserving owner-only exports.

Changes:

• Resolves public documentation labels to local Needs inventories.
• Adds duplicate-ID detection and integration coverage.
• Updates external-Needs documentation and examples.

File	Description
docs.bzl	Adds bundle inventory resolution and dependencies.
src/​helper_lib/​external_needs.py	Resolves internal inventory paths.
src/​extensions/​score_metamodel/​external_needs.py	Loads inventories and detects duplicates.
src/​extensions/​score_metamodel/​tests/​test_external_needs.py	Tests inventory parsing and URLs.
src/​tests/​docs_bzl/​test_upward_bundles.py	Tests parent-link resolution and collisions.
src/​tests/​docs_bzl/​scenarios/​upward_bundle_needs/​BUILD	Defines integration fixtures.
src/​tests/​docs_bzl/​scenarios/​upward_bundle_needs/​docs/​index.rst	Defines the parent Need.
src/​tests/​docs_bzl/​scenarios/​upward_bundle_needs/​component/​index.rst	Defines the child Need.
src/​tests/​docs_bzl/​scenarios/​reference_integration/​BUILD	Uses public docs inventory labels.
src/​tests/​docs_bzl/​scenarios/​reference_integration/​modern_module/​BUILD	Migrates external inventory labels.
docs/​reference/​bazel_macros.rst	Documents the new bundle API.
docs/​how-to/​source_to_doc_links.rst	Updates the linking example.
docs/​how-to/​setup.rst	Updates dependency setup.
docs/​how-to/​other_modules.rst	Explains cross-module imports.
docs/​concepts/​docs_deps.rst	Updates dependency concepts.
BUILD	Migrates the repository’s external Needs source.
.bazelrc	Removes Java configuration flags.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Public docs imports use a mismatched alias artifact path, and legacy data-based inventories are omitted from root-local exports.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Legacy data inventories are omitted from root export · New
• Synchronize Java configuration with PlantUML setup documentation

Resolved since last review (2)

• Forward external needs labels to the root local action
• Avoid conflating docs() with a standalone docs bundle

[github-actions]

Thanks for the pull request. This thread has been quiet for 30 days, so we are marking it as stale for now. Please take a quick look and let us know whether it is still up to date, still relevant, needs review, or is ready to merge. Any new activity will remove the stale label automatically. If nothing changes in the next 10 days, we will close it to keep the backlog current.