refactor(module-verification-report): split, tests, docs - #730
Draft
antonkri wants to merge 8 commits into
Draft
Conversation
Contributor
License Check Results🚀 The license check job ran with the Bazel command: bazel run --lockfile_mode=error //src:license-checkStatus: Click to expand output |
a-zw
reviewed
Aug 19, 2026
Comment on lines
+57
to
+59
| * - Config option | ||
| - ``:config: <path>`` — YAML file resolved relative to Sphinx's | ||
| ``srcdir`` (i.e. the directory containing ``conf.py``). |
Contributor
There was a problem hiding this comment.
Why a YAML file? Could we configure it via directive attributes instead?
Comment on lines
+61
to
+63
| * - Reads from the source tree | ||
| - Every ``.. mod::`` and ``.. comp::`` need, discovered by a | ||
| shallow regex scan at ``env-before-read-docs`` time. |
Contributor
There was a problem hiding this comment.
Reading the source tree is an anti-pattern. Could use a needs filter instead?
Comment on lines
+15
to
+20
| We deliberately do **not** query ``SphinxNeedsData`` here: doing so would | ||
| require reading the report source strictly after every source registering | ||
| a ``.. comp::`` / ``.. document::`` need, which forces | ||
| ``parallel_read_safe = False`` on the extension and produces two | ||
| Sphinx-level warnings per build (``the score_module_verification_report | ||
| extension is not safe for parallel reading`` / ``doing serial read``). |
Member
There was a problem hiding this comment.
looking through the PR, this is the most obvious red flag that we need to investigate. scanning source code is less than ideal.
antonkri
added a commit
to eclipse-score/baselibs
that referenced
this pull request
Aug 19, 2026
…cation_report Demonstrates the .. module-verification-report:: directive shipped by the ankr_mod_verf_report branch of score_docs_as_code (eclipse-score/docs-as-code#730): - Replace the hand-maintained ~2700-line docs/reporting/module_verification_report.rst with a two-line invocation of the new directive, driven by docs/reporting/module_report.yaml (module_id, feature_id, standard workproducts). - Bump score_docs_as_code git_override to a66bf953 (tip of ankr_mod_verf_report — refactor + tests + docs + testcase_annotations). - Drop the tracked bitmanipulation coverage HTML dump under coverage_reports/bitmanipulation and the derived docs/reporting/coverage_summary.json snapshot together with the tools/extract_coverage.py script that produced it. - Strip the legacy _load_coverage_substitutions() and testcase-badge setup() helpers from docs/conf.py — the former's input file is gone, the latter now lives in the shared extension as testcase_annotations.
antonkri
added a commit
to eclipse-score/baselibs
that referenced
this pull request
Aug 19, 2026
…cation_report Demonstrates the ``.. module-verification-report::`` directive shipped by the ``ankr_mod_verf_report`` branch of ``score_docs_as_code`` (eclipse-score/docs-as-code#730): - Add a new page ``docs/reporting/module_verification_report.rst`` that only carries the ``.. document::`` need and the two-line invocation of the new directive, driven by ``docs/reporting/module_report.yaml`` (module_id, feature_id, five standard workproducts). - Hook the new page into ``docs/index.rst`` under a fresh "Reporting" section in the top-level toctree. - Pin ``score_docs_as_code`` via ``git_override`` to a66bf953 — tip of ankr_mod_verf_report (refactor + tests + docs + testcase_annotations). - Extend the existing gtest suites for ``bit_manipulation``, ``bitmask_operators`` and the ``flatbuffers/details`` unit tests with additional cases that fill in the coverage the module report is meant to visualise. - Keep ``docs/conf.py`` minimal — no coverage-substitution helper, no testcase-badge ``setup`` (that logic now lives in the shared extension as ``testcase_annotations``).
antonkri
added a commit
to eclipse-score/baselibs
that referenced
this pull request
Aug 19, 2026
…cation_report Demonstrates the ``.. module-verification-report::`` directive shipped by the ``ankr_mod_verf_report`` branch of ``score_docs_as_code`` (eclipse-score/docs-as-code#730): - Add a new page ``docs/reporting/module_verification_report.rst`` that only carries the ``.. document::`` need and the two-line invocation of the new directive, driven by ``docs/reporting/module_report.yaml`` (module_id, feature_id, five standard workproducts). - Hook the new page into ``docs/index.rst`` under a fresh "Reporting" section in the top-level toctree. - Pin ``score_docs_as_code`` via ``git_override`` to a66bf953 — tip of ankr_mod_verf_report (refactor + tests + docs + testcase_annotations). - Extend the existing gtest suites for ``bit_manipulation``, ``bitmask_operators`` and the ``flatbuffers/details`` unit tests with additional cases that fill in the coverage the module report is meant to visualise. - Keep ``docs/conf.py`` minimal — no coverage-substitution helper, no testcase-badge ``setup`` (that logic now lives in the shared extension as ``testcase_annotations``).
Adds score_module_verification_report to the score_sphinx_bundle. Provides the .. module-verification-report:: directive that renders a per-module verification report body from a YAML config: - Component overview via sphinx-needs - Per-component Verification & Safety Analysis Documents table with Status column, delegated to sphinx-needs via .. needtable:: - Feature section (requirements / architecture / inspection stats) Extracted from baselibs' local docs/_ext/module_report.py so any consumer of docs-as-code can now use the directive without a local copy.
…dules Move the 909-line monolithic __init__.py into five thin modules so each layer can be reviewed and tested independently: * scanner.py - filesystem regex scan for .. mod:: / .. comp:: * coverage.py - coverage_summary.json loading + intro selection * templates.py - RST templates, WP-table CSS, default workproducts * rendering.py - pure template-expansion helpers * directive.py - the Sphinx directive class __init__.py is now a thin entry point (only setup() and re-exports). BUILD is aligned with score_mounts (sources / tests filegroups) and still exposes the same py_library target name, so the sphinx bundle consumer needs no change. The public surface is unchanged: the directive name, the config schema, env.module_verification_report_needs and the setup() return value all stay identical. Verified end-to-end against baselibs via local_path_override: the rendered report is byte-for-byte equivalent (same 42 wp-doc-table occurrences).
36 pytest cases exercising every branch of the pure layers: * test_scanner.py (15 tests): scan_rst_needs, module_includes, discover_components, scan_source_tree. Covers directive filtering, version-pinned includes, non-utf-8 files, deep walks, prefix mismatches, missing env attribute. * test_coverage.py (8 tests): load_coverage_summary (missing / invalid / null JSON, note_dependency), coverage_intro (measured vs. specification-only decision, trailing blank line). * test_rendering.py (13 tests): slug utilities, override vs. filter work-product rows, render_component / render_feature substitutions and end-to-end render_report assembly (with feature and component overrides). BUILD adds score_pytest(name = 'score_module_verification_report_tests'). Follows the existing score_mounts test pattern.
New src/extensions/docs/module_verification_report.rst documents: * the .. module-verification-report:: directive (arguments, options, fatal errors, warnings); * the YAML config schema, with defaults derived from module_id; * the sphinx-needs data model the extension reads or filters by (.. mod:: / .. comp:: / .. feat:: / .. wp:: / .. document:: / comp_req / comp_arc_* / feat_req / feat_arc_*); * what the read-hook actually scans and why (regex over srcdir, not SphinxNeedsData, to keep parallel_read_safe = True); * the report structure (CSS, feature section, component overview, per component sections); * work-product row rendering (override vs. sphinx-needs filter path, including the underscore-free slug normalisation); * the optional coverage_summary.json integration and its currently disabled section; * the 5-module architecture and public surface; * known limitations (feature-only repos, line-scan boundary conditions, nested DataTables cost); * how to run the unit tests. The extensions landing page (index.rst) gains a grid card and a toctree entry pointing to the new page.
…esult Moves the doctree-resolved handler that previously lived in each consumer's docs/conf.py (baselibs, etc.) into the shared extension as a new module 'testcase_annotations'. It walks doctree references whose visible text starts with 'testcase__', looks up the corresponding sphinx-needs entry via SphinxNeedsData.get_needs_view() and appends a coloured '(passed)' / '(failed)' / '(skipped)' / '(disabled)' badge in the same palette as the report pie charts. To keep the hook scoped to pages that actually render the directive (and to avoid affecting unrelated docs), the directive registers its docname in env.module_verification_report_docnames. The lifecycle is kept parallel-read-safe via three matching handlers: - env-before-read-docs -> init_docnames (create the set) - env-purge-doc -> purge_docname (drop stale entries) - env-merge-info -> merge_docnames (union worker sets) Also: - 16 unit tests covering every branch (colours, fallback, no-op paths, lifecycle handlers) — no dependency on sphinx-needs being installed. - Extension reference page updated: architecture table gains the new module, public surface list mentions the new env attribute, testing section mentions the new test file. - Version bumped 0.6 -> 0.7.
antonkri
force-pushed
the
ankr_mod_verf_report
branch
from
August 19, 2026 14:46
a66bf95 to
9a95bd0
Compare
antonkri
added a commit
to eclipse-score/baselibs
that referenced
this pull request
Aug 19, 2026
…cation_report Demonstrates the ``.. module-verification-report::`` directive shipped by the ``ankr_mod_verf_report`` branch of ``score_docs_as_code`` (eclipse-score/docs-as-code#730): - Add a new page ``docs/reporting/module_verification_report.rst`` that only carries the ``.. document::`` need and the two-line invocation of the new directive, driven by ``docs/reporting/module_report.yaml`` (module_id, feature_id, five standard workproducts). - Hook the new page into ``docs/index.rst`` under a fresh "Reporting" section in the top-level toctree. - Pin ``score_docs_as_code`` via ``git_override`` to a66bf953 — tip of ankr_mod_verf_report (refactor + tests + docs + testcase_annotations). - Extend the existing gtest suites for ``bit_manipulation``, ``bitmask_operators`` and the ``flatbuffers/details`` unit tests with additional cases that fill in the coverage the module report is meant to visualise. - Keep ``docs/conf.py`` minimal — no coverage-substitution helper, no testcase-badge ``setup`` (that logic now lives in the shared extension as ``testcase_annotations``).
…ent-prefix options
Replace the mandatory :config: YAML file with direct RST directive
options so the common case requires no external file at all:
.. module-verification-report::
:module-id: mod__mymodule
feature-id defaults to feat__<module-short> and component-prefix
defaults to comp__<module-short>_ when omitted. :config: is retained
as an optional escape hatch for non-default workproducts and
per-component doc-id overrides; fields in the file are ignored when
the corresponding directive option is set.
Also: 12 unit tests in test_directive.py covering the option-vs-config
precedence rules and all derivation paths; extension reference docs
updated (typical usage, at-a-glance table, directive reference,
config schema section retitled to 'advanced'); version unchanged.
antonkri
added a commit
to eclipse-score/baselibs
that referenced
this pull request
Aug 20, 2026
…cation_report Demonstrates the ``.. module-verification-report::`` directive shipped by the ``ankr_mod_verf_report`` branch of ``score_docs_as_code`` (eclipse-score/docs-as-code#730): - Add a new page ``docs/reporting/module_verification_report.rst`` that only carries the ``.. document::`` need and the two-line invocation of the new directive, driven by ``docs/reporting/module_report.yaml`` (module_id, feature_id, five standard workproducts). - Hook the new page into ``docs/index.rst`` under a fresh "Reporting" section in the top-level toctree. - Pin ``score_docs_as_code`` via ``git_override`` to a66bf953 — tip of ankr_mod_verf_report (refactor + tests + docs + testcase_annotations). - Extend the existing gtest suites for ``bit_manipulation``, ``bitmask_operators`` and the ``flatbuffers/details`` unit tests with additional cases that fill in the coverage the module report is meant to visualise. - Keep ``docs/conf.py`` minimal — no coverage-substitution helper, no testcase-badge ``setup`` (that logic now lives in the shared extension as ``testcase_annotations``).
antonkri
added a commit
to eclipse-score/baselibs
that referenced
this pull request
Aug 20, 2026
…cation_report Demonstrates the ``.. module-verification-report::`` directive shipped by the ``ankr_mod_verf_report`` branch of ``score_docs_as_code`` (eclipse-score/docs-as-code#730): - Add a new page ``docs/reporting/module_verification_report.rst`` that only carries the ``.. document::`` need and the two-line invocation of the new directive, driven by ``docs/reporting/module_report.yaml`` (module_id, feature_id, five standard workproducts). - Hook the new page into ``docs/index.rst`` under a fresh "Reporting" section in the top-level toctree. - Pin ``score_docs_as_code`` via ``git_override`` to a66bf953 — tip of ankr_mod_verf_report (refactor + tests + docs + testcase_annotations). - Extend the existing gtest suites for ``bit_manipulation``, ``bitmask_operators`` and the ``flatbuffers/details`` unit tests with additional cases that fill in the coverage the module report is meant to visualise. - Keep ``docs/conf.py`` minimal — no coverage-substitution helper, no testcase-badge ``setup`` (that logic now lives in the shared extension as ``testcase_annotations``).
antonkri
added a commit
to eclipse-score/baselibs
that referenced
this pull request
Aug 20, 2026
…cation_report Demonstrates the ``.. module-verification-report::`` directive shipped by the ``ankr_mod_verf_report`` branch of ``score_docs_as_code`` (eclipse-score/docs-as-code#730): - Add a new page ``docs/reporting/module_verification_report.rst`` that only carries the ``.. document::`` need and the two-line invocation of the new directive, driven by ``docs/reporting/module_report.yaml`` (module_id, feature_id, five standard workproducts). - Hook the new page into ``docs/index.rst`` under a fresh "Reporting" section in the top-level toctree. - Pin ``score_docs_as_code`` via ``git_override`` to a66bf953 — tip of ankr_mod_verf_report (refactor + tests + docs + testcase_annotations). - Extend the existing gtest suites for ``bit_manipulation``, ``bitmask_operators`` and the ``flatbuffers/details`` unit tests with additional cases that fill in the coverage the module report is meant to visualise. - Keep ``docs/conf.py`` minimal — no coverage-substitution helper, no testcase-badge ``setup`` (that logic now lives in the shared extension as ``testcase_annotations``).
…omponents: option
Instead of scanning .rst files at env-before-read-docs time to resolve
the mod's :includes: list, component ids are now declared directly on
the directive:
.. module-verification-report::
:module-id: mod__baselibs
:feature-id: feat__baselibs
:components: comp__baselibs_json,
comp__baselibs_bit_manipulation, ...
Changes:
- scanner.py removed entirely (no filesystem walk, no regex parsing,
no env.module_verification_report_needs attribute).
- env-before-read-docs hook for scan_source_tree removed from setup().
- _parse_components() helper in directive.py: splits on commas, strips
optional [version==N] qualifiers, derives slug by stripping
component_prefix, derives title from slug (underscore -> space,
title-case).
- Error if :components: is empty / omitted.
- Version bumped 0.7 -> 0.8.
- test_scanner.py removed; test_directive.py extended with 9 tests for
_parse_components (id parsing, version stripping, title derivation,
whitespace handling, multi-line values, prefix mismatch).
- Reference docs updated: typical usage, at-a-glance table, directive
reference (:components: option), 'No filesystem scan' rationale
section replaces 'Filesystem scan' section, architecture table updated
to five modules, limitations updated, testing section updated.
antonkri
force-pushed
the
ankr_mod_verf_report
branch
from
August 20, 2026 08:51
bab116b to
1cb9250
Compare
antonkri
added a commit
to eclipse-score/baselibs
that referenced
this pull request
Aug 20, 2026
…cation_report Demonstrates the ``.. module-verification-report::`` directive shipped by the ``ankr_mod_verf_report`` branch of ``score_docs_as_code`` (eclipse-score/docs-as-code#730): - Add a new page ``docs/reporting/module_verification_report.rst`` that only carries the ``.. document::`` need and the two-line invocation of the new directive, driven by ``docs/reporting/module_report.yaml`` (module_id, feature_id, five standard workproducts). - Hook the new page into ``docs/index.rst`` under a fresh "Reporting" section in the top-level toctree. - Pin ``score_docs_as_code`` via ``git_override`` to a66bf953 — tip of ankr_mod_verf_report (refactor + tests + docs + testcase_annotations). - Extend the existing gtest suites for ``bit_manipulation``, ``bitmask_operators`` and the ``flatbuffers/details`` unit tests with additional cases that fill in the coverage the module report is meant to visualise. - Keep ``docs/conf.py`` minimal — no coverage-substitution helper, no testcase-badge ``setup`` (that logic now lives in the shared extension as ``testcase_annotations``).
antonkri
force-pushed
the
ankr_mod_verf_report
branch
2 times, most recently
from
August 20, 2026 10:45
d3f2719 to
0af2a93
Compare
Contributor
|
Documentation preview for this pull request is available at: |
antonkri
force-pushed
the
ankr_mod_verf_report
branch
4 times, most recently
from
August 20, 2026 11:34
590b548 to
5c956f5
Compare
…inished Add consistency_checks.py with a build-finished hook that warns when: - a component listed in :components: is not in the module need's :includes: - the feature ID is not in the component need's :belongs_to: The check is entirely passive (Sphinx warnings, no build failure) and requires no configuration in consumer repos. The registry is populated by the directive during the read phase and is parallel-read safe via init_registry / purge_registry / merge_registry lifecycle hooks. 17 new unit tests (75 total). Version bumped to 0.9.
antonkri
force-pushed
the
ankr_mod_verf_report
branch
from
August 20, 2026 12:12
5c956f5 to
6fdb693
Compare
antonkri
added a commit
to eclipse-score/baselibs
that referenced
this pull request
Aug 20, 2026
…cation_report Demonstrates the ``.. module-verification-report::`` directive shipped by the ``ankr_mod_verf_report`` branch of ``score_docs_as_code`` (eclipse-score/docs-as-code#730): - Add a new page ``docs/reporting/module_verification_report.rst`` that only carries the ``.. document::`` need and the two-line invocation of the new directive, driven by ``docs/reporting/module_report.yaml`` (module_id, feature_id, five standard workproducts). - Hook the new page into ``docs/index.rst`` under a fresh "Reporting" section in the top-level toctree. - Pin ``score_docs_as_code`` via ``git_override`` to a66bf953 — tip of ankr_mod_verf_report (refactor + tests + docs + testcase_annotations). - Extend the existing gtest suites for ``bit_manipulation``, ``bitmask_operators`` and the ``flatbuffers/details`` unit tests with additional cases that fill in the coverage the module report is meant to visualise. - Keep ``docs/conf.py`` minimal — no coverage-substitution helper, no testcase-badge ``setup`` (that logic now lives in the shared extension as ``testcase_annotations``).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR introduces an extension to generate a module verification report, that can be used by every module. For detailed documentation see module_verification_report.rst
See eclipse-score/baselibs#491 (comment) for an example usage