Skip to content

docs: integrate mw::log traceability into Sphinx - #365

Draft
Y-Vaishnavi wants to merge 2 commits into
eclipse-score:mainfrom
Y-Vaishnavi:vy/docs-integrate-mw-log-traceability
Draft

Y-Vaishnavi wants to merge 2 commits into
eclipse-score:mainfrom
Y-Vaishnavi:vy/docs-integrate-mw-log-traceability

Conversation

@Y-Vaishnavi

@Y-Vaishnavi Y-Vaishnavi commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • integrate the generated mw::log dependable-element docs into the standalone Sphinx preview build (//docs/sphinx:sphinx_doc)
  • add mw::log dependable-element navigation (requirements, architecture, dependability analysis, LOBSTER traceability) to the sidebar
  • add a "Safety Reports" link to the mw::log dependable-element report on the main published docs site (docs/index.rst)
  • keep //:docs_check passing alongside this change

Details

The traceability report was already being generated, but it wasn't linked from anywhere in the Sphinx documentation. This change:

  • mounts the generated dependable-element RST content into //docs/sphinx:sphinx_doc via its _rst facade, and embeds it in that build's sidebar toctree
  • adds a plain hyperlink to the report from the main published docs (docs/index.rst)

Note: //docs/sphinx:sphinx_doc is a local-preview-only target — it isn't built/published by .github/workflows/docs.yml (only //:docs is). The "Safety Reports" link in docs/index.rst currently points at a path that isn't produced by the //:docs build either, so it won't resolve on the live site yet; making it resolve would require additional CI wiring as a follow-up.

Validation

bazel build //docs/sphinx:sphinx_doc //:docs_check //:docs

# To preview the embedded report locally:
xdg-open bazel-bin/docs/sphinx/sphinx_doc/html/index.html

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run --lockfile_mode=error //:license-check

Status: ⚠️ Needs Review

Click to expand output
[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.6.0) and connecting to it...
INFO: Invocation ID: 24608d9f-bdd3-46f5-a7d9-72b3796e5b17
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 4 packages loaded
DEBUG: /home/runner/.bazel/external/score_docs_as_code+/docs.bzl:705:14: INFO: ⚠️ DEPRECATED: Passing a Needs inventory through docs(data = [...]) is deprecated!!! Move it to external_needs = [...] instead.
WARNING: Target pattern parsing failed.
ERROR: Skipping '//:license-check': no such target '//:license-check': target 'license-check' not declared in package '' defined by /home/runner/work/logging/logging/BUILD
ERROR: no such target '//:license-check': target 'license-check' not declared in package '' defined by /home/runner/work/logging/logging/BUILD
INFO: Elapsed time: 16.217s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

@Y-Vaishnavi
Y-Vaishnavi force-pushed the vy/docs-integrate-mw-log-traceability branch from abd67f5 to bfa2212 Compare October 19, 2026 14:00
@Y-Vaishnavi
Y-Vaishnavi force-pushed the vy/docs-integrate-mw-log-traceability branch from 2d0010d to bfa2212 Compare October 19, 2026 14:14
@Y-Vaishnavi
Y-Vaishnavi force-pushed the vy/docs-integrate-mw-log-traceability branch from e1e3bb1 to 5760a33 Compare October 19, 2026 15:53
@Y-Vaishnavi
Y-Vaishnavi force-pushed the vy/docs-integrate-mw-log-traceability branch from 5760a33 to f88b7ec Compare October 21, 2026 04:45
@Y-Vaishnavi
Y-Vaishnavi force-pushed the vy/docs-integrate-mw-log-traceability branch from f88b7ec to a23d620 Compare October 21, 2026 07:04
@Y-Vaishnavi
Y-Vaishnavi force-pushed the vy/docs-integrate-mw-log-traceability branch from a23d620 to 6776081 Compare October 21, 2026 07:11
@Y-Vaishnavi
Y-Vaishnavi force-pushed the vy/docs-integrate-mw-log-traceability branch from 6776081 to 2ce5aef Compare October 21, 2026 07:41
Comment thread docs/sphinx/index.rst
@@ -0,0 +1,134 @@
..

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already a duplication of the existing repo structure. This should not be needed

Squashed stack that adds the mw::log dependability prerequisites and wires the generated traceability report into the main Sphinx site.
CI currently publishes //:docs (the docs() macro tree), which has no
mechanism to pull in the generated mw::log dependable-element/LOBSTER
traceability report - only //docs/sphinx:sphinx_doc embeds that content
via docs_library_deps. As a result the report would never appear on the
published GitHub Pages site even after merge.

Add a build_sphinx_package py_binary that copies sphinx_doc's bazel-bin
output into _build/, the directory the shared cicd-workflows docs.yml
uploads as the github-pages artifact, and point the build-docs job at
it instead of //:docs. The docs_check (verify-only) job is unaffected.

Signed-off-by: vaishnavi yendole <vaishnavi.yendole@bti.bmwgroup.com>

This branch is waiting to be deployed

1 waiting deployment
workflow-approval — 1c1df1fd Waiting Oct 21, 2026 by Y-Vaishnavi via approval #909
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

2 participants