Rule Reference

Documentation Rules

sphinx_module

Builds Sphinx-based HTML documentation from RST/MD source files. Supports cross-module dependencies and automatic HTML merging.

sphinx_module(
    name  = "my_docs",
    srcs  = glob(["docs/**/*.rst", "docs/**/*.md"]),
    index = "docs/index.rst",
    deps  = ["@external_module//:docs"],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name; also the output directory prefix
`srcs`	label list	yes	RST, MD, image, and PlantUML source files
`index`	label	yes	Path to the root `index.rst`
`deps`	label list	no	Other `sphinx_module` or `dependable_element` targets for cross-referencing and HTML merging (default `[]`)
`sphinx`	label	no	Override the Sphinx binary (default: toolchain-provided binary)
`testonly`	bool	no	If `True`, only testonly targets may depend on this (default `False`)
`visibility`	—	no	Bazel visibility

Generated targets:

<name> — HTML output under bazel-bin/<name>/html/; use in deps of other sphinx_module targets.
<name>_needs — needs.json produced by the needs builder; consumed transitively by downstream modules for cross-module {requirement:downstream-ref} resolution. See Two-phase Sphinx build for the full data-flow description.

Artifact Rules

All artifact rules produce a SphinxSourcesInfo provider (documentation page) and carry typed traceability information for downstream structural rules.

assumed_system_requirements

System-level requirements that the SEooC receives from its operational context. These are too broad to be assigned to a single component.

assumed_system_requirements(
    name = "sys_req",
    srcs = ["docs/assumed_system_requirements.trlc"],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name
`srcs`	label list	yes	`.trlc` files containing `AssumedSystemReq` records
`deps`	label list	no	Reserved for consistency; unused at root level (default `[]`)
`visibility`	—	no	Bazel visibility (default `["//visibility:public"]`)

Generated targets: <name> (documentation), <name>_test (TRLC syntax/type validation)

feature_requirements

High-level requirements derived from AssumedSystemReq. Operate at the integration level; can only be satisfied by multiple components working together.

feature_requirements(
    name = "features",
    srcs = ["docs/features.trlc"],
    deps = [":sys_req"],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name
`srcs`	label list	yes	`.trlc` files containing `FeatReq` records
`deps`	label list	no	`assumed_system_requirements` targets for `derived_from` cross-reference resolution (default `[]`)
`visibility`	—	no	Bazel visibility (default `["//visibility:public"]`)

Generated targets: <name> (documentation), <name>_test (TRLC validation including cross-reference checks)

component_requirements

Requirements assigned to exactly one component; directly implementable and testable within that component.

component_requirements(
    name = "comp_req",
    srcs = ["docs/requirements.trlc"],
    deps = [":features"],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name
`srcs`	label list	yes	`.trlc` files containing `CompReq` records
`deps`	label list	no	`feature_requirements` or `assumed_system_requirements` targets for `derived_from` resolution (default `[]`)
`visibility`	—	no	Bazel visibility (default `["//visibility:public"]`)

Generated targets: <name> (documentation), <name>_test (TRLC validation)

assumptions_of_use

Conditions that the integrating project must fulfil when using this SEooC.

assumptions_of_use(
    name         = "aous",
    srcs         = ["docs/assumptions.trlc"],
    requirements = [":features"],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name
`srcs`	label list	yes	`.trlc` files containing `AoU` records
`requirements`	label list	no	`feature_requirements` or `component_requirements` targets that these AoUs trace to (default `[]`)
`visibility`	—	no	Bazel visibility

Generated targets: <name> (documentation), <name>_test (TRLC validation)

glossary

Collects glossary pages for Sphinx and forwards them to downstream documentation assembly (for example through dependable_element).

glossary(
   name = "project_glossary",
   srcs = ["docs/glossary.rst"],
)

Example glossary source (.rst):

Glossary
========

.. glossary::

   integrity level
      ASIL rating (QM, A, B, C, D) indicating required safety rigor.

   component
      Software unit with defined interfaces, implementation, and tests.

Attribute	Type	Required	Description
`name`	string	yes	Target name
`srcs`	label list	yes	`.rst` files containing glossary definitions
`visibility`	—	no	Bazel visibility

Generated targets: <name> (documentation; no standalone test)

architectural_design

Bundles static, dynamic, and public-API architecture views into a single target. Provides ArchitecturalDesignInfo consumed by dependable_element and fmea.

architectural_design(
    name       = "arch",
    static     = ["docs/static_design.puml"],
    dynamic    = ["docs/sequence.puml"],
    public_api = ["docs/public_api.puml"],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name
`static`	label list	no	Static-view files (`.puml`, `.rst`, `.md`, `.svg`, `.png`) (default `[]`)
`dynamic`	label list	no	Dynamic-view files (default `[]`)
`public_api`	label list	no	Public-API diagram files (`.puml`); also generates traceability items for safety analysis (default `[]`)
`visibility`	—	no	Bazel visibility

Generated targets: <name> (provides ArchitecturalDesignInfo; no standalone test — consistency is validated as part of bazel test //pkg:my_element)

unit_design

Attaches code-level design diagrams to a unit target. Accepts the same file types as architectural_design but scoped to a single unit’s internal implementation.

unit_design(
    name    = "my_unit_design",
    static  = ["class_diagram.rst", "class_diagram.puml"],
    dynamic = ["sequence_diagram.puml"],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name
`static`	label list	no	Static-view files (class diagrams, data-structure diagrams). When an `.rst` fragment references a `.puml` via `.. uml::`, list both files together (default `[]`)
`dynamic`	label list	no	Dynamic-view files (sequence, state diagrams) (default `[]`)
`visibility`	—	no	Bazel visibility

Generated targets: <name> (no standalone test; diagrams are consumed by the parent unit)

fmea

Bundles failure modes, control measures, and FTA diagrams into a single FMEA documentation target.

fmea(
    name            = "my_fmea",
    failuremodes    = ["docs/failuremodes.trlc"],
    controlmeasures = ["docs/controlmeasures.trlc"],
    root_causes     = ["docs/fta.puml"],
    arch_design     = ":arch",
)

Attribute	Type	Required	Description
`name`	string	yes	Target name
`failuremodes`	label list	no	`.trlc` files containing `FailureMode` records (default `[]`)
`controlmeasures`	label list	no	`.trlc` files containing `ControlMeasure` records (default `[]`)
`root_causes`	label list	no	FTA PlantUML diagram files (`.puml` / `.plantuml`) (default `[]`)
`arch_design`	label	no	`architectural_design` target for interface traceability (default `None`)
`visibility`	—	no	Bazel visibility

Generated targets: <name> (documentation; no standalone test — traceability validated via the parent dependability_analysis)

dependability_analysis

Wraps one or more fmea targets into a complete safety-analysis package. Running bazel test validates the full FMEA traceability chain.

dependability_analysis(
    name = "analysis",
    fmea = [":my_fmea"],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name
`fmea`	label list	yes	`fmea` targets to include in this analysis
`visibility`	—	no	Bazel visibility

Generated targets: <name> (build → documentation; bazel test //pkg:analysis → full FMEA traceability validation)

Structural Rules

unit

The smallest independently testable software element. Ties together implementation targets, test targets, and an optional unit_design target. The name must match the unit name used in the static architecture PlantUML diagram.

unit(
    name           = "KeyValueStore",
    unit_design    = [":kvs_unit_design"],
    implementation = [":kvs_lib"],
    tests          = [":kvs_unit_test"],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name; must match the `<<unit>>` name in the static PlantUML diagram
`unit_design`	label list	yes	`unit_design` targets describing the unit’s internal design
`implementation`	label list	yes	Library or binary targets that implement this unit (e.g. `cc_library`, `py_library`)
`tests`	label list	yes	Test targets that verify this unit (may be `[]`)
`scope`	label list	no	Additional targets needed by the implementation but not listed in `implementation` (default `[]`)
`testonly`	bool	no	If `True`, only testonly targets may depend on this unit (default `True`)
`visibility`	—	no	Bazel visibility

Generated targets: <name> (provides UnitInfo; no standalone test — the listed tests run via bazel test //pkg:... directly)

component

Groups unit (and optionally nested component) targets into a logical subsystem. Associates component-level requirements and integration tests. The name must match the component name in the static architecture PlantUML diagram.

component(
    name         = "KvsComponent",
    requirements = [":comp_req"],
    components   = [":KeyValueStore", ":StorageBackend"],
    tests        = [],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name; must match the `<<component>>` name in the static PlantUML diagram
`requirements`	label list	yes	`component_requirements` or `feature_requirements` targets for this component
`components`	label list	no	Nested `unit` or `component` targets (default `[]`)
`tests`	label list	yes	Integration test targets for the component as a whole (may be `[]`)
`testonly`	bool	no	If `True`, only testonly targets may depend on this component (default `True`)
`visibility`	—	no	Bazel visibility

Generated targets: <name> (provides ComponentInfo; no standalone test — the listed tests run via bazel test //pkg:... directly)

dependable_element

Assembles all process artefacts into a complete SEooC. Runs Sphinx to generate unified HTML documentation and enforces architecture consistency, traceability, and scope checks at build/test time.

dependable_element(
    name                   = "my_seooc",
    integrity_level        = "B",
    assumptions_of_use     = [":aous"],
    requirements           = [":features"],
    architectural_design   = [":arch"],
    dependability_analysis = [":analysis"],
    components             = [":kvs_component"],
    tests                  = [],
)

Attribute	Type	Required	Description
`name`	string	yes	Target name; also becomes the SEooC documentation title
`integrity_level`	string	yes	`"A"`, `"B"`, `"C"`, or `"D"` (D is highest: D > C > B > A)
`assumptions_of_use`	label list	yes	`assumptions_of_use` targets
`requirements`	label list	yes	`feature_requirements` or `assumed_system_requirements` targets
`architectural_design`	label list	yes	`architectural_design` targets
`dependability_analysis`	label list	yes	`dependability_analysis` targets
`components`	label list	yes	`component` or `unit` targets that implement this SEooC
`tests`	label list	yes	System-level test targets (may be `[]`)
`checklists`	label list	no	Additional `.rst` / `.md` checklist files (default `[]`)
`deps`	label list	no	Other `dependable_element` targets for cross-referencing and HTML merging (default `[]`)
`aou_forwarding`	label	no	A YAML file selecting which received AoUs to chain-forward to elements that depend on this one. Each entry requires an `aou_id` and a `justification`. Own AoUs (from `assumptions_of_use`) are always forwarded automatically.
`maturity`	string	no	`"release"` (default) or `"development"` — in development mode, scope violations and architecture errors are downgraded to warnings
`testonly`	bool	no	If `True`, only testonly targets may depend on this element (default `True`)
`visibility`	—	no	Bazel visibility

Generated targets:

Target	Purpose
`<name>`	Main target: build runs Sphinx; `bazel test` runs the traceability check
`<name>_doc`	Internal `sphinx_module` target; usable as `deps` in other Sphinx builds
`<name>_index`	Internal artefact-collection and architecture-validation target