2. Step 2 — Join the documentation and process-compliance checks#

What it unlocks

Docs & process checks — Your module’s documentation appears in the single, combined docs site that is built and published for the whole integration — and, just as importantly, your module’s requirements, architecture and other process artifacts are validated against the S-CORE process as part of the same build. This is usually the first thing you extend the integration with after the module is in the graph.

Building the docs is not only about rendering pages. The integration uses the docs-as-code toolchain (score_docs_as_code, pulled in via score_sphinx_bundle in docs/conf.py), which runs the S-CORE metamodel checks on every needs object: requirements, architecture elements, safety artifacts and their links must conform to the process model defined in score_process. If your module’s requirements/architecture are malformed, unlinked or violate the metamodel, the docs build (and therefore CI) fails — so wiring your module in here is what gets its process artifacts continuously checked, not just published.

The integration builds one Sphinx site that merges the docs of every integrated module. To pull yours in:

  1. Add your module’s needs_json to the docs(...) rule’s data list in the top-level BUILD file:

    docs(
    data = [
        "@score_persistency//:needs_json",
        # ...
        "@score_my_module//:needs_json",
    ],
    known_good = "known_good.json",
    source_dir = "docs",
)

    This requires your module to expose a //:needs_json target (i.e. it is a docs-as-code module).

  2. Add a toctree entry so the module shows up in the navigation. Which page you edit depends on what kind of module it is — the site groups modules into two top-level sections, each backed by its own .rst page:

    Section

    Page to edit

    Put your module here if it is…

    Modules

    docs/sw_components.rst

    an S-CORE software module that ships in the integration — i.e. it lives under modules.target_sw in known_good.json (communication, persistency, logging, orchestrator, baselibs, …). This is the common case.

    Process, Methods & Tools

    docs/process_methods_tools.rst

    a tooling / process repo from modules.tooling (platform, process, docs-as-code) rather than a shipped software module.

    For a normal software module, add the entry to the Modules toctree in docs/sw_components.rst, next to the existing modules:

    Modules
=======

.. toctree::
   :titlesonly:
   :maxdepth: 1

   _collections/score_persistency/docs/index
   _collections/score_logging/docs/index
   # ...
   _collections/score_my_module/docs/index

    The _collections/score_my_module/docs/index path is not a file in this repository — the docs build mounts every module’s documentation under _collections/<module-repo-name>/ at build time. So the path must be:

    • score_my_module — the module/repository name as registered in known_good.json (the @score_my_module repo), and

    • docs/index — the path of the documentation root inside that module’s repository (most modules use docs/index; match whatever your module actually exposes via its needs_json docs target).

Build the full docs locally to verify your module shows up — or use the live-preview server which rebuilds on every change:

# one-shot full build incl. all modules
bazel run //:docs_combo

# live preview in the browser (auto-rebuild)
bazel run //:live_preview_combo_experimental

The docs are built and published by the test_and_docs workflow (see CI checks).

Note

Planned refactoring. Today documentation generation is entangled with unit tests, coverage and feature integration tests in the single test_and_docs workflow (test_and_docs.yml). This should be refactored: the documentation build (including the metamodel / process-compliance checks) belongs in a dedicated, reusable workflow shared across all S-CORE repositories, hosted centrally in the cicd-workflows repository, instead of being duplicated and maintained per repo.