Tracability improvements - needs type autodiscovery (#545)

* Fix: clarify requirement type autodiscovery override
* Feat: traceability improvements (#578)
* Fix: Upgrade of tests & schema
* Feat: Reworking scripts into Sphinx Extensions
* Fix: Documentation, Complexity, PR Comments
* Fix: Fixing PR comments, linting & formatting
* Fix: Fix accessing of renamed options

---------

Co-authored-by: Maximilian Sören Pollak <maximilian.pollak@qorix.com>

Author: FScholPer

docs/conf.py

@@ -10,6 +10,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 # *******************************************************************************
+import matplotlib
 
 project = "Score Docs-as-Code"
 project_url = "https://eclipse-score.github.io/docs-as-code/"
@@ -18,3 +19,4 @@
 extensions = [
     "score_sphinx_bundle",
 ]
+matplotlib.rcParamsDefault["savefig.bbox"] = "tight"

docs/how-to/dashboards_and_quality_gates.rst

@@ -27,7 +27,7 @@ Goals:
 What You Get
 ------------
 
-With the ``docs(...)`` macro and ``score_metamodel`` extension enabled, your
+With the ``docs(...)`` macro and ``score_metamodel`` as well as the ```score_metrics`` extensions enabled, your
 repository can:
 
 - build an HTML dashboard from its own Sphinx needs,
@@ -40,30 +40,44 @@ Typical Setup
 
 For details, see :ref:`setup`.
 
-Minimal Configuration Example
------------------------------
+Configuration
+-------------
+
+Default Behavior (No Configuration Needed)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default, ``score_metrics`` autodiscovers requirement types from the
+repository needs present in the current build.
+Requirement types are identified from ``needs_types`` entries tagged with ``requirement``.
+
+This is the recommended setup for most repositories.
 
-In ``docs/conf.py``:
+Optional Override for Requirement Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If a repository needs to force a specific set of requirement types, set an
+explicit override in ``docs/conf.py``:
 
 .. code-block:: python
 
-   score_metamodel_requirement_types = "feat_req,comp_req,aou_req"
-   score_metamodel_include_external_needs = False
+   score_metrics_requirement_types = "feat_req,comp_req,aou_req"
+
+When this setting is provided, the explicit list is used instead of
+autodiscovery.
 
-Use ``score_metamodel_include_external_needs = True`` only in repositories that
+Use ``score_metrics_include_external_needs = True`` only in repositories that
 intentionally aggregate requirements across module dependencies, such as
-integration repositories. Use ``False`` for module repositories to gate only on
-local traceability.
+integration repositories.
 
 Building the Dashboard
 ----------------------
 
-After building/running any docs command (i.e. ``bazel build //:needs_json`` or ``bazel run //:docs_check`` are the fastest):
+After building/running any docs and test command (i.e. ``bazel build //:needs_json`` or ``bazel run //:docs_check``, ``bazel run //:docs``, ``bazel test //...``):
 
-The documentation build writes ``metrics.json`` via ``score_metamodel``, and the ``needs_json`` artifact contains:
+The documentation build writes ``metrics.json`` via ``score_metrics``, and the ``needs_json`` artifact contains:
 
-- ``bazel-bin/needs_json/_build/needs/needs.json``
-- ``bazel-bin/needs_json/_build/needs/metrics.json``
+- ``_build/needs.json``
+- ``_build/metrics.json``
 
 The dashboard charts and the CI gate both use the same computed metrics.
 
@@ -87,13 +101,13 @@ There are two common modes:
 
 **Module repository**
 
-- Set ``score_metamodel_include_external_needs = False``.
+- No setting needed. Local-only scope is the default.
 - Gate only on the needs owned by the repository itself.
 - Use this for per-module implementation progress and traceability.
 
 **Integration repository**
 
-- Set ``score_metamodel_include_external_needs = True``.
+- Set ``score_metrics_include_external_needs = True``.
 - Aggregate requirements across module dependencies when that is the intended
   repository purpose.
 - Use this for system or integration-level dashboards.
@@ -136,10 +150,75 @@ For a new consumer repository:
 4. Introduce modest thresholds in CI.
 5. Raise thresholds over time as the repository matures.
 
-Related Guides
---------------
+..
+   ╓                                                          ╖
+   ║ Some portions generated by Github Copilot                ║
+   ╙                                                          ╜
+
+Needpie Usage Guide (Quick and Practical)
+=========================================
+
+Use these examples as ready-to-copy templates for dashboard-style pie charts.
+
+Tips for readable charts
+------------------------
+
+- Keep labels short and audience-friendly.
+- Put the most important category first.
+- Use high-contrast colors that are easy to distinguish.
+- Avoid red/green-only combinations when possible.
+
+Recommended color palette
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This palette is generally easier to read:
+
+- ``#4E79A7`` (blue)
+- ``#F28E2B`` (orange)
+- ``#59A14F`` (green)
+- ``#B07AA1`` (purple)
+
+Example 1: Overall view (including remaining/unlinked)
+------------------------------------------------------
+
+.. code-block:: rst
+
+   .. needpie:: Overall Requirement Coverage
+      :labels: Remaining (no selected links), With Test Link, With Code Link, Fully Linked
+      :colors: #4E79A7, #F28E2B, #59A14F, #B07AA1
+      :filter-func: score_metrics.sphinx_filters.get_metrics_with_first_value_total(overall_metrics:total,overall_metrics:with_test_link,overall_metrics:with_code_link,overall_metrics:fully_linked)
+
+This chart shows:
+
+- remaining requirements (calculated from total),
+- requirements with test link,
+- requirements with code link,
+- fully linked requirements.
+
+.. needpie:: Overall Requirement Coverage
+   :labels: Remaining (no selected links), With Test Link, With Code Link, Fully Linked
+   :colors: #4E79A7, #F28E2B, #59A14F, #B07AA1
+   :filter-func: score_metrics.sphinx_filters.get_metrics_with_first_value_total(overall_metrics:total,overall_metrics:with_test_link,overall_metrics:with_code_link,overall_metrics:fully_linked)
+
+Example 2: Focused view (no total-based remainder)
+--------------------------------------------------
+
+This chart shows direct values only (no remaining slice):
+
+- tool requirements with test link,
+- tool requirements with code link,
+- overall fully linked requirements.
+
+.. needpie:: Tool Requirements Snapshot
+   :labels: Tool Req With Test Link, Tool Req With Code Link, Fully Linked (Overall)
+   :colors: #F28E2B, #4E79A7, #59A14F
+   :filter-func: score_metrics.sphinx_filters.get_just_metrics(metrics_by_type:tool_req:with_test_link,metrics_by_type:tool_req:with_code_link,overall_metrics:fully_linked)
+
+Presentation checklist
+----------------------
+
+Before publishing, quickly verify:
 
-- :ref:`setup`
-- :doc:`other_modules`
-- :doc:`source_to_doc_links`
-- :doc:`test_to_doc_links`
+- labels are understandable for non-technical readers,
+- colors are distinct and readable on your page theme,
+- title clearly says what the chart represents.

docs/internals/requirements/implementation_state.rst

@@ -28,8 +28,6 @@ docs-as-code as a Bazel dependency.
 Pages
 -----
 
-- ``implementation_state`` describes tooling coverage: implemented capabilities,
-  source-code links, test links, full linkage, and process-to-tool mapping.
 - ``tooling_verification`` describes verification evidence for the tooling
   itself, including test results and testcase metadata.
 
@@ -39,5 +37,4 @@ Pages
    capabilities
    process_overview
    requirements
-   implementation_state
    tooling_verification

docs/internals/requirements/index.rst

@@ -852,6 +852,18 @@ Testing
     - If Partially/FullyVerifies are set in Unit Test these shall link to Component Requirements
 
 
+.. tool_req:: Provide Metrics for linked requirements
+   :id: tool_req__docs_test_linkage_metrics
+   :tags: Testing
+   :version: 1
+   :implemented: YES
+   :parent_covered: NO: Placeholder process requirement
+   :satisfies: gd_req__verification_reporting
+   :status: invalid
+
+   Docs-AS-Code shall provide a way to gather statistics on linkages to implementation(source_code_links) & tests(testlink) for all needs.
+   It shall also be possible to filter these by type and use the provided statistics in the documentation (via diagrams drawn from it etc.)
+
 🧪 Tool Verification Reports
 ############################
 

docs/internals/requirements/requirements.rst

@@ -53,6 +53,17 @@ Overview
       No skipped or disabled tests are expected in the current dataset.
 
 
+How many requirements are linked
+---------------------------------
+
+*This shows how many of our requirements are linked with tests, in source code, both or neither.*
+
+.. needpie:: Overall Requirement Coverage
+   :labels: Remaining (no selected links), With Test Link, With Code Link, Fully Linked
+   :colors: #4E79A7, #F28E2B, #59A14F, #B07AA1
+   :filter-func: score_metrics.sphinx_filters.get_metrics_with_first_value_total(overall_metrics:total,overall_metrics:with_test_link,overall_metrics:with_code_link,overall_metrics:fully_linked)
+
+
 Testcase Metadata Overview
 --------------------------