eclipse-score · pawelrutkaq · Sep 8, 2026 · Sep 8, 2026
@@ -14,6 +14,7 @@
 load("@score_docs_as_code//:docs.bzl", "docs")
 load("@score_tooling//:defs.bzl", "setup_starpls")
 load("@score_tooling//third_party/format:macros.bzl", "use_format_targets")
+load("//bazel_common:docs_bundles.bzl", "DOCS_BUNDLES")
 
 # Alias causing doc build here being independet of what doc-as-code do.
 # This allows to changge labels of real doc build indepedent of pull_request_target
@@ -24,46 +25,14 @@ alias(
 )
 
 # Docs-as-code
+#
+# The bundle mounts are generated from known_good.json into
+# //bazel_common:docs_bundles.bzl: every module is mounted under its group's section
+# (target_sw -> modules/, tooling -> process_methods_tools/) unless it sets
+# '"docs": false' there. Change the module list in known_good.json, not here, and
+# regenerate with scripts/known_good/update_module_from_known_good.py.
 docs(
-    bundles = [
-        # Software components
-        # TODO Remove and replace with generation for know_good.json !
-        # "@score_communication//:needs_json",  # no docs_sources
-        {
-            "bundle": "@score_lifecycle//:docs_bundle",
-            "mount_at": "modules/score_lifecycle",
-        },
-        {
-            "bundle": "@score_logging//:docs_bundle",
-            "mount_at": "modules/score_logging",
-        },
-        {
-            "bundle": "@score_persistency//:docs_bundle",
-            "mount_at": "modules/score_persistency",
-        },
-        {
-            "bundle": "@score_kyron//:docs_bundle",
-            "mount_at": "modules/score_kyron",
-        },
-        {
-            "bundle": "@score_baselibs//:docs_bundle",
-            "mount_at": "modules/score_baselibs",
-        },
-
-        # Process methods and tools (PMT)
-        {
-            "bundle": "@score_platform//:docs_bundle",
-            "mount_at": "process_methods_tools/score_platform",
-        },
-        {
-            "bundle": "@score_process_description//:docs_bundle",
-            "mount_at": "process_methods_tools/score_process_description",
-        },
-        {
-            "bundle": "@score_docs_as_code//:docs_bundle",
-            "mount_at": "process_methods_tools/score_docs_as_code",
-        },
-    ],
+    bundles = DOCS_BUNDLES,
     known_good = "known_good.json",
     source_dir = "docs",
 )

@@ -0,0 +1,55 @@
+# *******************************************************************************
+# Copyright (c) 2025 Contributors to the Eclipse Foundation
+#
+# See the NOTICE file(s) distributed with this work for additional
+# information regarding copyright ownership.
+#
+# This program and the accompanying materials are made available under the
+# terms of the Apache License Version 2.0 which is available at
+# https://www.apache.org/licenses/LICENSE-2.0
+#
+# SPDX-License-Identifier: Apache-2.0
+# *******************************************************************************
+
+# Generated from known_good.json at 2026-08-28T09:19:12Z
+# Do not edit manually - use scripts/known_good/update_module_from_known_good.py --known known_good.json --output-dir-modules bazel_common
+
+# Documentation bundle mounts for the docs() macro in the root BUILD file.
+DOCS_BUNDLES = [
+    {
+        "bundle": "@score_baselibs//:docs_bundle",
+        "mount_at": "modules/score_baselibs",
+    },
+    {
+        "bundle": "@score_persistency//:docs_bundle",
+        "mount_at": "modules/score_persistency",
+    },
+    {
+        "bundle": "@score_kyron//:docs_bundle",
+        "mount_at": "modules/score_kyron",
+    },
+    {
+        "bundle": "@score_lifecycle//:docs_bundle",
+        "mount_at": "modules/score_lifecycle",
+    },
+    {
+        "bundle": "@score_logging//:docs_bundle",
+        "mount_at": "modules/score_logging",
+    },
+    {
+        "bundle": "@score_itf//:docs_bundle",
+        "mount_at": "process_methods_tools/score_itf",
+    },
+    {
+        "bundle": "@score_platform//:docs_bundle",
+        "mount_at": "process_methods_tools/score_platform",
+    },
+    {
+        "bundle": "@score_docs_as_code//:docs_bundle",
+        "mount_at": "process_methods_tools/score_docs_as_code",
+    },
+    {
+        "bundle": "@score_process_description//:docs_bundle",
+        "mount_at": "process_methods_tools/score_process_description",
+    },
+]
@@ -29,8 +29,8 @@ Use this as a final review before opening your pull request:
        patches referenced if needed; ``known_good_correct`` and ``bzlmod-lock``
        checks green.
    * - 2 · Documentation
-     - ``needs_json`` added to ``//:docs`` data and toctree entry in
-       ``modules.rst``; ``//:docs_combo`` shows the module.
+     - mounted automatically from ``known_good.json`` (no ``"docs": false``);
+       ``bazel run //:docs`` shows the module in its section.
    * - 3 · Unit tests (default platform)
      - module compiles and unit tests pass on ``--config=linux-x86_64`` via
        ``quality_runners.py``; ``metadata`` tuned if needed.

@@ -119,7 +119,7 @@ The consolidated outputs published by the integration. They are built by
      - Source / target
    * - Consolidated documentation
      - All integrated module docs merged into one Sphinx site.
-     - `BUILD <https://github.com/eclipse-score/reference_integration/blob/main/BUILD>`_ ``docs(...)`` → ``bazel run //:docs_combo``
+     - `BUILD <https://github.com/eclipse-score/reference_integration/blob/main/BUILD>`_ ``docs(...)`` → ``bazel run //:docs``
    * - Platform verification report
      - Per-release requirements/architecture verification, safety analyses and
        per-test-case results.

@@ -38,86 +38,83 @@ docs build (and therefore CI) fails — so wiring your module in here is what ge
 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:
-
-#. Add your module's ``needs_json`` to the ``docs(...)`` rule's ``data`` list in
-   the top-level `BUILD <https://github.com/eclipse-score/reference_integration/blob/main/BUILD>`_ file:
-
-   .. code-block:: python
-
-      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).
-
-#. 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:
-
-   .. list-table::
-      :header-rows: 1
-      :widths: 22 30 48
-
-      * - Section
-        - Page to edit
-        - Put your module here if it is…
-      * - **Modules**
-        - `docs/modules.rst <https://github.com/eclipse-score/reference_integration/blob/main/docs/modules.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, kyron, baselibs, …). This is the common
-          case.
-      * - **Process, Methods & Tools**
-        - `docs/process_methods_tools.rst <https://github.com/eclipse-score/reference_integration/blob/main/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/modules.rst <https://github.com/eclipse-score/reference_integration/blob/main/docs/modules.rst>`_, next to the existing
-   modules:
-
-   .. code-block:: rst
-
-      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).
+module, and it does so straight from ``known_good.json``: **a module that is in
+the integration has its documentation in the site by default**. There is nothing
+to add to the top-level ``BUILD`` file.
+
+What happens under the hood: a module that calls docs-as-code's ``docs()`` macro
+automatically exposes a public ``//:docs_bundle`` target.
+``scripts/known_good/update_module_from_known_good.py`` turns every module in
+``known_good.json`` into one mount entry in
+`bazel_common/docs_bundles.bzl <https://github.com/eclipse-score/reference_integration/blob/main/bazel_common/docs_bundles.bzl>`_,
+which the ``docs(bundles = DOCS_BUNDLES, ...)`` call in the top-level `BUILD
+<https://github.com/eclipse-score/reference_integration/blob/main/BUILD>`_ file
+consumes. **Which of the two site sections your module lands in follows from the
+group it sits in** — no extra declaration, and no toctree to edit: the section
+pages (``docs/modules/index.rst`` and ``docs/process_methods_tools/index.rst``)
+carry empty toctrees that the mounts fill at build time.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 26 26 48
+
+   * - Group in ``known_good.json``
+     - Mounted under
+     - Your module belongs here if it is…
+   * - ``modules.target_sw``
+     - ``modules/<module_name>``
+     - an S-CORE **software module** that ships in the integration
+       (communication, persistency, logging, kyron, baselibs, …). This is the
+       common case.
+   * - ``modules.tooling``
+     - ``process_methods_tools/<module_name>``
+     - a **tooling / process** repo (platform, process_description,
+       docs-as-code, …) rather than a shipped software module.
+
+So for a normal module you do nothing beyond adding it to ``known_good.json``
+and re-running the generator:
+
+.. code-block:: bash
+
+   scripts/known_good/update_module_from_known_good.py --known known_good.json \
+       --output-dir-modules bazel_common
+
+Commit the regenerated files together with your ``known_good.json`` change —
+the :ref:`ci_checks` regenerate them and fail if they drift.
+
+Opting a module out
+~~~~~~~~~~~~~~~~~~~
+
+Some modules expose no ``//:docs_bundle``: they do not call ``docs()`` at all,
+or their root package cannot be loaded from the integration's dependency graph.
+Mounting those would fail the docs build on a missing target, so they opt out
+explicitly with ``"docs": false``:
+
+.. code-block:: json
+
+   "score_bazel_platforms": {
+       "repo": "https://github.com/eclipse-score/bazel_platforms.git",
+       "docs": false,
+       "hash": "607672cdf2f05f21af7113dab0849726dd59bf86"
+   }
+
+Treat ``"docs": false`` as a gap to close, not a normal state — the point of the
+default is that documentation and its process checks are opt-out, not opt-in.
+
+If you need a non-default mount, ``docs`` also accepts an object with
+``bundle``, ``mount_at`` and ``attach_to`` keys, which are passed through to the
+``docs()`` macro unchanged.
 
 Build the full docs locally to verify your module shows up — or use the
 live-preview server which rebuilds on every change:
 
 .. code-block:: bash
 
    # one-shot full build incl. all modules
-   bazel run //:docs_combo
+   bazel run //:docs
 
    # live preview in the browser (auto-rebuild)
-   bazel run //:live_preview_combo_experimental
+   bazel run //:live_preview
 
 The docs are built and published by the ``test_and_docs`` workflow (see
 :ref:`ci_checks`).

@@ -33,6 +33,7 @@
             },
             "score_communication": {
                 "repo": "https://github.com/eclipse-score/communication.git",
+                "docs": false,
                 "hash": "b22ed6d314313c87eb06ca916efda9a71ec53cc6",
                 "bazel_patches": [
                     "//patches/communication:001-expose-comm-examples.patch",
@@ -138,6 +139,7 @@
             },
             "score_time": {
                 "repo": "https://github.com/eclipse-score/time.git",
+                "docs": false,
                 "hash": "c4f0194a3b496757e5c193ed8618fc3f45a868a5",
                 "bazel_patches": [],
                 "metadata": {
@@ -152,6 +154,7 @@
             },
             "score_config_management": {
                 "repo": "https://github.com/eclipse-score/config_management.git",
+                "docs": false,
                 "hash": "e0489b190ed6d2fa183b9a8063e2dba4f6378505",
                 "bazel_patches": [
                     "//patches/config_management:001-adapt-proxy-api-and-remove-internal-targets.patch"
@@ -182,6 +185,7 @@
         "tooling": {
             "score_crates": {
                 "repo": "https://github.com/eclipse-score/score-crates.git",
+                "docs": false,
                 "hash": "4656dda8f04a3d88c8089f63111195840cfbd9e3"
             },
             "score_itf": {
@@ -190,6 +194,7 @@
             },
             "score_tooling": {
                 "repo": "https://github.com/eclipse-score/tooling.git",
+                "docs": false,
                 "bazel_patches": [
                     "//patches/tooling:001-expose-aspect-rules-lint-non-dev.patch"
                 ],
@@ -204,10 +209,12 @@
             },
             "score_bazel_platforms": {
                 "repo": "https://github.com/eclipse-score/bazel_platforms.git",
+                "docs": false,
                 "hash": "607672cdf2f05f21af7113dab0849726dd59bf86"
             },
             "score_test_scenarios": {
                 "repo": "https://github.com/eclipse-score/testing_tools.git",
+                "docs": false,
                 "hash": "fec712d490ff5d46fae91332bafac4777b300026"
             },
             "score_docs_as_code": {
@@ -220,6 +227,7 @@
             },
             "score_bazel_cpp_toolchains": {
                 "repo": "https://github.com/eclipse-score/bazel_cpp_toolchains.git",
+                "docs": false,
                 "hash": "bd12c5344053f842fae4623dada5716dfb43e61d",
                 "metadata": {
                     "code_root_path": "//score/...",

@@ -12,6 +12,6 @@
 # *******************************************************************************
 """Models for score reference integration tools."""
 
-from .module import Module, Metadata
+from .module import Docs, Module, Metadata
 
-__all__ = ["Module", "Metadata"]
+__all__ = ["Docs", "Module", "Metadata"]