Reference Other Modules#

This document explains how to enable cross-module (bi-directional) linking between documentation modules with Sphinx-Needs in this project. In short:

  1. Make the other module available to Bazel via the MODULE (aka MODULE.bazel) file.

  2. Add the external module’s documentation targets to your docs(data=[…]) target so Sphinx can see the other module’s built inventory.

  3. Reference remote needs using the normal Sphinx-Needs referencing syntax.

Details and Example#

1) Include the other module in MODULE.bazel#

The consumer module must declare the other modules as dependencies in the MODULE.bazel file so Bazel can fetch them. There are multiple ways to do this depending on how you manage third-party/local modules (git, local overrides, etc.).

A minimal example (add or extend the existing bazel_deps stanza):

bazel_dep(name = "score_process", version = "1.5.3")

2) Extend your docs rule so Sphinx picks up the other module’s inventory#

The documentation build is exposed via a Bazel macro that accepts an external_needs parameter for external :needs_json_file targets. Use external_needs instead of data when the target produces needs JSON — data is meant for non-needs runfiles (e.g. custom tool outputs).

Example BUILD snippet (consumer module):

load("@score_docs_as_code//:docs.bzl", "docs")
docs(
  data = [
     "@score_process//:needs_json",
  ],
  source_dir = "docs",
)

More details in Bi-directional Traceability.

3) Reference needs across modules#

Once the other module’s are defined as dependencies as explained above, you can reference their needs IDs in the usual Sphinx-Needs way. The important part is that the inventory name that Sphinx-Needs looks up matches the module that produced the needs entries.

Example in reStructuredText:

See the requirement :need:`gd_req__req_traceability`, for example.

Which results in:

See the requirement gd_req__req_traceability, for example.

See the Sphinx-Needs documentation for more details on cross-referencing needs.

Data vs. external_needs#

It might seem like data and external_needs behave nearly the same.

docs(
  data           = ["@score_process//:needs_json"],
  external_needs = ["@score_process//:needs_json_file"],  # same?
)

For a :docs they behave the same, but for :docs_combo they do not. In a combo build, the data are treated differently and will include the documentation instead of just link the needs online. However, external_needs will always be hyperlinks.