Reference Docs in Source Code

In your C++/Rust/Python source code, you want to reference requirements (needs). The docs-as-code tool will create backlinks in the documentation in two steps:

1. You add a special comment in your source code that references the need ID.

2. Scan for those comments and provide needs links to your documentation.

For an example result, look at the attribute source_code_link of Enforces title wording rules (tool_req__docs_common_attr_title).

Comments in Source Code

Use a comment and start with req-Id: or req-traceability: followed by the need ID.

# req-Id: TOOL_REQ__EXAMPLE_ID
# req-traceability: TOOL_REQ__EXAMPLE_ID

For other languages (C++, Rust, etc.), use the appropriate comment syntax.

Scanning Source Code for Links

In your BUILD files, pass the implementation targets to the docs rule as code_targets. Their srcs, hdrs, and textual_hdrs are scanned, including those of their deps recursively. This means that a cc_executable also covers source files from the cc_library targets it uses. You may also pass filegroups; their files are scanned directly.

cc_library(
   name = "some_library",
   srcs = [
       "bar.cpp",
   ],
)

cc_executable(
   name = "some_application",
   srcs = ["main.cpp"],
   deps = [":some_library"],
)

docs(
   data = [
          "@score_process_description//:needs_json",
      ],
      source_dir = "docs",
      code_targets = [":some_application"],
      primary_need_id = "comp__some_component",
)

primary_need_id is optional and identifies the single Need representing the bundle’s primary subject. A bundle can contain many other Needs; target metadata is attached only to this explicitly selected Need. The ID is never derived from the Bazel bundle name.