Skip to content

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

Merged
rmaddikery merged 2 commits into
eclipse-score:mainfrom
Y-Vaishnavi:vy/docs-integrate-mw-log-traceability
Oct 26, 2026
Merged

docs: integrate mw::log traceability into Sphinx#365
rmaddikery merged 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 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • Publishes the generated mw::log dependable-element report (requirements, architecture, dependability analysis, LOBSTER traceability) on the main published docs site
  • Adds a persistent sidebar entry ("mw::log Backend Dependable Element Report") linking to it
  • //:docs_check still passes
  • Report now resolves on the live GitHub Pages site (no extra CI wiring needed)

Details

The report was already generated via dependable_element() (//score/mw/log/dependability:dependable_element_mw_log_backend_doc), but wasn't linked anywhere or published.

This change:

  • Adds docs/dependable_elements/index.rst, wired into docs/index.rst's toctree → shows up sitewide in the sidebar
  • Links via a plain hyperlink to the standalone generated report
  • Adds scripts/publish_dependable_element_reports.py (//:publish_dependable_element_reports) to copy the report's HTML into _build/dependable_elements/ after //:docs builds
  • CI (docs.yml) chains this via && bazel run --lockfile_mode=error //:publish_dependable_element_reports, so both ship together in the same published _build/

No duplicate Sphinx site is introduced — //:docs stays the single canonical site.

Validation

xdg-open _build/index.html

Then navigate: Component Documentation → mw::log Backend Dependable Element Report

@Y-Vaishnavi
Y-Vaishnavi marked this pull request as draft October 19, 2026 13:53
@github-actions

github-actions Bot commented Oct 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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: ddfcc5ba-4ee1-44f6-9c51-47c9061a8175
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:716: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: 15.933s
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 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
rmaddikery
rmaddikery reviewed Oct 21, 2026
View reviewed changes
Comment thread docs/sphinx/index.rst Outdated
@@ -0,0 +1,134 @@
..

@rmaddikery rmaddikery Oct 21, 2026

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

rmaddikery
rmaddikery reviewed Oct 22, 2026
View reviewed changes
Comment thread docs/sphinx/index.rst Outdated
@@ -0,0 +1,68 @@
..

@rmaddikery rmaddikery Oct 22, 2026

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.

Again, still a duplication of index. Replace this with: docs/index.rst

rmaddikery
rmaddikery reviewed Oct 22, 2026
View reviewed changes
Comment thread scripts/build_sphinx_package.py Outdated

if out.exists():
_make_writable(out)
shutil.rmtree(out)

@rmaddikery rmaddikery Oct 22, 2026

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 not ideal in CI env. We should populate from bazel gen artifacts

@github-actions

github-actions Bot commented Oct 23, 2026

Copy link
Copy Markdown
Contributor

The created documentation from the pull request is available at: docu-html

Y-Vaishnavi and others added 2 commits October 23, 2026 12:10
@Y-Vaishnavi @rmaddikery
docs: publish mw::log dependable-element report alongside main site
7017590 
Add a lightweight docs/dependable_elements/index.rst page, wired into
docs/index.rst's toctree, that links to the standalone Sphinx report
already generated by the dependable_element() macro for the mw::log
backend (//score/mw/log/dependability:dependable_element_mw_log_backend_doc).

A new scripts/publish_dependable_element_reports.py (run via the
//:publish_dependable_element_reports py_binary) copies that report's
pre-built HTML output into _build/dependable_elements/ after the main
docs() build, so it is included in the published GitHub Pages site
without duplicating or replacing any existing content.

CI (.github/workflows/docs.yml) chains the publish step after the
primary //:docs build so both outputs ship together.
@rmaddikery
split docs build and publish, keep Bazel caches shared
635d054 
- Bump the docs workflow to a version that sets up
bazel caching for every bazel run in the job, so
the chained target runs share caches.

- build on pull_request with read-only permissions
- add docs-publish.yml (workflow_run) for deployment
- drop docs-verify, now covered by the docs build
- locate the dependable-element report via runfiles

This branch was successfully deployed

1 active deployment
workflow-approval — 635d0545 Deployed Oct 23, 2026 by rmaddikery via run-tests / coverage approval gate #1417
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@rmaddikery rmaddikery rmaddikery approved these changes
@antonkri antonkri Awaiting requested review from antonkri antonkri is a code owner
@4og 4og Awaiting requested review from 4og
@hoppe-and-dreams hoppe-and-dreams Awaiting requested review from hoppe-and-dreams hoppe-and-dreams is a code owner
@pawelrutkaq pawelrutkaq Awaiting requested review from pawelrutkaq pawelrutkaq is a code owner
@arsibo arsibo Awaiting requested review from arsibo arsibo is a code owner

Assignees

No one assigned

Labels

None yet

Projects

LOG - Logging FT
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@Y-Vaishnavi @rmaddikery