Doc-as-Code		status: evaluated
tags: tool_management, tools_documentation safety_affected: YES security_affected: YES tcl: LOW tool_version: v8.1.2 version: 3 realizes: wp__tool_verification_report

doc_tool__doc_as_code		Tool Verification Report

Doc-as-Code Tool Verification Report#

Introduction#

Scope and purpose#

The S-CORE Docs-as-Code tool (Bazel module score_docs_as_code) builds HTML documentation from RST/Markdown sources — process description, requirements, and traceability — and validates content against the S-CORE metamodel.

Inputs and outputs#

Inputs: RST/Markdown sources, Sphinx configuration (conf.py), the S-CORE metamodel (metamodel.yaml), Bazel build files, source-code links (sourcelinks_json) and test results (testlinks).
Outputs: HTML documentation (_build/), needs/traceability data (needs.json), coverage/linkage statistics (metrics.json).

        graph LR
   src@{ shape: docs, label: "RST/Markdown sources (+ assets)" }
   code@{ shape: docs, label: "C++/Rust/Python sources" }
   srclinks@{ shape: doc, label: "sourcelinks" }
   cfg@{ shape: docs, label: "Config (conf.py, metamodel.yaml, Bazel)" }
   tests@{ shape: docs, label: "Test results" }
   dac@{ shape: subproc, label: "Doc-as-Code" }
   html@{ shape: docs, label: "HTML docs" }
   needs@{ shape: doc, label: "needs.json" }
   metrics@{ shape: docs, label: "metrics.json" }

   src --> dac
   code --> srclinks --> dac
   cfg --> dac
   tests --> dac
   dac --> html
   dac --> needs
   dac --> metrics

Available information#

Repository: eclipse-score/docs-as-code
Documentation: https://eclipse-score.github.io/docs-as-code/v8.1.2/
Bazel module name: score_docs_as_code

Installation and integration#

Installation#

The tool is consumed as a Bazel module. Declare the dependency in MODULE.bazel:

bazel_dep(name = "score_docs_as_code", version = "8.1.2")

and the S-CORE registry in .bazelrc:

common --registry=https://raw.githubusercontent.com/eclipse-score/bazel_registry/main/
common --registry=https://bcr.bazel.build

Invoke the docs() macro from the root BUILD file:

load("@score_docs_as_code//:docs.bzl", "docs")
docs(
    project = "My Project",
    project_url = "https://github.com/eclipse-score/my-project",
    source_dir = "docs",
)

For local development, bazel run //:ide_support creates a Python virtual environment (.venv_docs) with all Sphinx extensions pre-installed for IDE support (Esbonio). The macro’s build targets (//:docs, //:docs_check, //:docs_link_check, //:traceability_gate, //:live_preview, //:ide_support) are documented in the Build commands reference.

Tool sources live in the docs-as-code repository under src/extensions/ (Sphinx extensions) and docs.bzl (Bazel macros). The default metamodel is bundled at @score_docs_as_code//src/extensions/score_metamodel:metamodel_yaml and may be overridden via the metamodel parameter. See the Bazel macros reference for macro parameters and the score_metamodel design for metamodel definition and validation checks.

Integration#

The tool is the central documentation hub of the S-CORE Bazel toolchain, used by all modules to build, check, and publish documentation.

Cross-module linking supports two modes:

External needs import: reference another module’s :needs_json_file target via the external_needs parameter of docs() to cross-reference need IDs across modules (e.g., :need:`gd_req__example_id`).
Bundle mounting: mount another module’s :docs_bundle target via the bundles parameter; the mounted sources join the consuming build, with placement controlled by mount_at (docname prefix) and attach_to (toctree anchor). See How to mount external sources.

Within a repository, Sphinx combines documentation sources (RST/Markdown), needs JSON, source-code links (sourcelinks_json) and test metadata through the S-CORE extensions (score_metamodel, score_metrics, score_mounts) to produce HTML, needs.json and metrics.json.

Environment#

Operating system: Linux — the S-CORE DevContainer (canonical, recommended), WSL2, or native.
Build system: Bazel (rules_python, sphinxdocs) fetches all toolchains and dependencies, including a remote JDK 17 for PlantUML diagrams when no local Java is present.

Safety evaluation#

Use cases were derived from the process requirements and the docs-as-code Tool Requirements.

The facts below are shared by use cases and only referenced in each Malfunctions cell.

Build/CI behavior: Builds run with -W; any warning trips CI. The safety-relevant danger is the silent failure — a missing warning or a wrong output published undetected. A loud CI abort is safe: no wrong output enters the baseline.

PR Review: Repository contents are the source of truth and every change is reviewed by a committer (rl__committer, doc_concept__wp_inspections). Still, for silent wrong outputs the gated CI stays green.

Derived-view: The rendered HTML output is a derived view; the authoritative safety artifacts are mostly the source-controlled work products. There are two exceptions, the architecture views (see M4) and backlinks (see M8). Rendering/preview defects affect reviewer convenience, not safety evidence.

Table 31 S-CORE Docs-as-Code safety evaluation#
Malfunction identification	Use case description	Malfunctions	Impact on safety?	Impact safety measures available?	Impact safety detection sufficient?	Further additional safety measure required?	Confidence (automatic calculation)
M1	Document metamodel enforcement — enforce document types, mandatory attributes (id, status, security, safety, realizes), etc. See, for example, gd_req__doc_attr_status, gd_req__req_attr_uid, gd_req__req_attr_safety, gd_req__arch_attr_safety, gd_req__req_check_mandatory.	Silent false-negative, too-permissive `metamodel.yaml` regex accepted with no guard, or a check bug skips a case.	yes	yes: PR review	no: Qualify metamodel enforcement.	yes (qualification)	low
M2	Safety-critical linking enforcement. See gd_req__req_linkage_safety.	Silent false-negative: Allow links which cannot be safe derivations.	yes	yes: PR review	no: Qualify graph checks. The clearest gap is `satisfied_by` (and arguably `covers`), which carry the same “target at least as safe” obligation as the checked `fulfils`/`implements` yet are unconstrained.	yes (qualification)	low
M3	Requirements coverage statistics — count, per requirement type, the requirements carrying a `testlink`, compute link-coverage percentages. See gd_req__verification_reporting.	Silent wrong-output: a coverage statistic computed wrong.	yes	no	no: Qualify coverage statistics.	yes (qualification)	low
M4	Architecture visualization — generate architecture diagrams. See gd_req__arch_viewpoints.	Silent wrong-output: a diagram misrepresents the architecture.	yes	yes: PR review includes architecture inspection	yes	no	high
M5	Test linkage — for each `testcase` need, resolve its `partially_verifies`/`fully_verifies` references against the needs set. See gd_req__req_attr_testlink, gd_req__verification_reporting.	Silent wrong-output: Safety case believes the requirement is tested where it is not.	yes	no	no: Qualify linkage statistics	yes (qualification)	low
M6	Test reference check. See gd_req__req_attr_testlink.	Silent wrong-output: Test references an outdated/missing requirement.	yes	yes: PR review	no: Qualify test reference check	yes (qualification)	low
M7	Listing assumptions of use — safety manuals use `needtable` to communicate safety-critical assumptions of use to users. See gd_guidl__saf_man, wp__platform_safety_manual.	Silent wrong-output: `aou_req` items might be missing or wrong.	yes	yes: PR review	no: Qualify `needtable`	yes: qualification	low
M8	Backlinks — for bi-directional traceability, generate correct backlinks for links between Needs items. See doc_concept__general_traceability.	Silent wrong-output: Generated backlinks are wrong or missing.	yes	no	no: Qualify backlinks in HTML	yes (qualification)	low
M9	Documentation generation — apart from the aspects not covered by previous malfunctions. See gd_req__doc_attributes_manual, gd_req__doc_attr_status.	Incomplete, outdated, or mis-rendered HTML.	no: Derived-view	no	yes	no	high

Security evaluation#

The threat model reduces to a single class: source tampering. The tool has no runtime attack surface — it is a build-time Sphinx extension reading source-controlled inputs and writing generated output.

Table 32 S-CORE Docs-as-Code security evaluation#
Threat identification	Use case description	Threats	Impact on security?	Impact security measures available?	Impact security detection sufficient?	Further additional security measure required?
T1	Source tampering — applies to all tool use cases. See gd_req__req_attr_security, gd_req__arch_attr_security, gd_req__req_linkage, gd_req__req_traceability, gd_req__arch_linkage_security_trace.	An attacker with write access tampers with sources, configuration, or extension code to weaken/disable security checks or inject misleading content into published output.	yes	yes: PR review.	yes	no

Result#

The final Tool Confidence Level is LOW, the worst case across all use cases.

S-CORE Docs-as-Code requires qualification for use in safety-related software development according to ISO 26262.

Optional Section for Tool Qualification#

Based on method: validation of the software tool

Requirements and testing aspects#

Tool requirements: Defined in the docs-as-code internal documentation: Tool Requirements. Each tool_req specifies a mandatory attribute enforcement, linkage rule, or metamodel check implemented by the score_metamodel Sphinx extension.
Test cases: Results and testcase metadata are published in Tooling Verification. There is additional description about File-Based Testing.
Requirements coverage: Per-requirement test and code linkage is tracked in Requirement Test Coverage and also published as metrics.json.

The table below maps each malfunction of the safety and security evaluation which needs to be qualified to the docs-as-code tool requirements (tool_req) that implement the corresponding checks.

Table 33 Test coverage for necessary qualification#
Malfunction	Tool requirements (with testlinks)	Tool requirements (without testlinks)
M1	tool_req__docs_common_attr_id_scheme, tool_req__docs_common_attr_status, tool_req__docs_common_attr_description, tool_req__docs_common_attr_title, tool_req__docs_common_attr_desc_wording, tool_req__docs_common_attr_security tool_req__docs_saf_attrs_mandatory, tool_req__docs_sec_attr_stride_threat_id, tool_req__docs_sec_attrs_mandatory	tool_req__docs_doc_generic_mandatory, tool_req__docs_common_attr_id, tool_req__docs_common_attr_safety, tool_req__docs_common_attr_version, tool_req__docs_common_attr_suspicious, tool_req__docs_req_attr_rationale, tool_req__docs_req_attr_reqtype, tool_req__docs_req_attr_testcov, tool_req__docs_req_attr_validity_correctness, tool_req__docs_req_attr_validity_consistency, tool_req__arch_linkage_safety, tool_req__arch_consistency_interf, tool_req__docs_tvr_safety, tool_req__docs_tvr_security, tool_req__docs_tvr_status, tool_req__docs_tvr_version, tool_req__docs_tvr_confidence_level, tool_req__docs_saf_attrs_mitigated_by, tool_req__docs_saf_attrs_mitigation_issue, tool_req__docs_saf_attrs_sufficient, tool_req__docs_saf_attrs_sufficient_check, tool_req__docs_saf_attrs_content, tool_req__docs_saf_attrs_violates, tool_req__docs_saf_attr_fmea_fault_id, tool_req__docs_saf_attr_fmea_failure_effect
M2	tool_req__docs_common_attr_safety_link_check, tool_req__docs_req_arch_link_safety_to_arch	tool_req__docs_req_link_satisfies_allowed, tool_req__docs_req_link_covers_aou, tool_req__docs_arch_link_fulfils, tool_req__docs_arch_link_fulfils_aou, tool_req__docs_arch_link_aou_check, tool_req__docs_arch_link_safety_to_req, tool_req__docs_req_arch_link_safety_to_arch, tool_req__docs_arch_link_security
M3		tool_req__docs_verification_report_need
M5	tool_req__docs_test_link_testcase, tool_req__docs_test_linkage_metrics	tool_req__docs_verification_report_need, tool_req__docs_test_metadata_mandatory_1, tool_req__docs_test_metadata_mandatory_2, tool_req__docs_test_metadata_link_levels
M6	tool_req__docs_test_link_testcase
M7	tool_req__docs_req_types	tool_req__docs_req_link_covers_aou, tool_req__docs_arch_link_fulfils_aou
M8		tool_req__docs_req_link_satisfies_allowed

Analysis perspective#

Architectural design

The internal architecture is described via its Sphinx extensions and Bazel macros:

Extensions overview — score_metamodel, score_metrics, score_mounts, score_cross_module_compatibility and other extensions.
score_metamodel design — metamodel definition, validation checks (local, graph-based, prohibited-word), and the check lifecycle.
Bazel macros reference — the docs() macro and its generated targets.
Build commands — public and internal Bazel targets.