From 01d0c746768baf58f4c59a9021d10790102711c1 Mon Sep 17 00:00:00 2001
From: Andreas Zwinkau <Andreas.Zwinkau@etas.com>
Date: Wed, 5 Aug 2026 13:05:59 +0200
Subject: [PATCH 1/2] feat: how-to for generated docs

---
 docs/how-to/generated_docs.rst | 115 +++++++++++++++++++++++++++++++++
 docs/how-to/index.rst          |   1 +
 2 files changed, 116 insertions(+)
 create mode 100644 docs/how-to/generated_docs.rst

diff --git a/docs/how-to/generated_docs.rst b/docs/how-to/generated_docs.rst
new file mode 100644
index 000000000..2bc259b7d
--- /dev/null
+++ b/docs/how-to/generated_docs.rst
@@ -0,0 +1,115 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2026 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
+   # *******************************************************************************
+
+.. _howto_generated_docs:
+
+Integrate Generated Documentation
+=================================
+
+When a script or tool creates documentation content at build time, collect it
+with a ``docs_bundle`` and mount the bundle into your documentation tree.
+
+You find a `complete working example <https://github.com/eclipse-score/docs-as-code/tree/main/src/extensions/score_metamodel/docs/>`_
+in the :ref:`metamodel-types-visualization`.
+
+Step 1: Generate the RST Files
+------------------------------
+
+Use a ``genrule`` (or **any build action**) that writes RST files.
+
+.. code-block:: starlark
+   :caption: In your BUILD file
+
+   genrule(
+       name = "generate_design_rst",
+       srcs = ["design_model.yaml"],
+       outs = ["generated/index.rst"],
+       cmd = "$(location :design_rst_tool) --output $(location generated/index.rst) $<",
+       tools = [":design_rst_tool"],
+   )
+
+If your tool writes many files (a second RST, a Mermaid ``.mmd`` diagram, or
+any other companion asset), add all of them to ``outs``.
+Sphinx directives in the RST (for example ``.. mermaid:: arch.mmd``) use
+relative paths because all files stay in the same generated directory.
+
+Make sure the generated files include an ``index.rst`` at the root of the
+output directory.
+
+Verify:
+  ``bazel build :generate_design_rst`` must succeed.
+  Inspect the output at ``bazel-bin/<package>/generated/index.rst``.
+
+Step 2: Declare the Bundle
+--------------------------
+
+Wrap the generated files in a ``docs_bundle`` with the ``data`` attribute.
+Do not use ``srcs`` — that is for handwritten sources in the source tree.
+
+.. code-block:: starlark
+   :caption: In your BUILD file
+
+   docs_bundle(
+       name = "design_bundle",
+       data = [":generate_design_rst"],
+   )
+
+Verify:
+  ``bazel build :design_bundle`` must succeed.
+  The bundle now holds the generated file but does not yet place it anywhere.
+
+Step 3: Mount the Bundle
+------------------------
+
+Add the bundle to your ``docs()`` call.
+
+.. code-block:: starlark
+   :caption: In your BUILD file
+
+   docs(
+       source_dir = "docs",
+       bundles = [{
+           "bundle": ":design_bundle",
+           "mount_at": "design",
+           "attach_to": "index",
+       }],
+   )
+
+The generated page becomes ``design/index.html`` in the output.
+``mount_at`` sets the target path; ``attach_to`` adds the page to that
+document's toctree (defaults to the parent ``index`` when omitted).
+
+Verify:
+  ``bazel run //:docs`` must succeed.
+  Open ``_build/design/index.html`` and confirm the generated content.
+
+
+Common Issues
+-------------
+
+**The bundle is mounted but the generated file does not appear, or Sphinx
+warns about files not in any toctree.**
+Make sure the genrule's ``outs`` uses a subdirectory (for example
+``generated/index.rst``) and not a bare ``index.rst``.
+``score_mounts`` mounts the parent directory of the genrule output.
+Without a subdirectory, it mounts the genrule output root — which often
+contains other build artifacts and causes Sphinx warnings.
+
+**Attach-to target is missing.**
+``attach_to`` must point to a document that exists in the host tree.
+When unsure, point it at ``"index"`` (the host project's root ``index.rst``).
+
+.. seealso::
+
+   :ref:`docs_concept_mounts` and the :ref:`howto_mount_external_sources` How-To.
diff --git a/docs/how-to/index.rst b/docs/how-to/index.rst
index cb2d38a29..f4aa7a3ce 100644
--- a/docs/how-to/index.rst
+++ b/docs/how-to/index.rst
@@ -29,4 +29,5 @@ Here you find practical guides on how to use docs-as-code.
    dashboards_and_quality_gates
    source_to_doc_links
    test_to_doc_links
+   generated_docs
    add_extensions

From 65779a92ada9207d813cd081a1126ae48b39117c Mon Sep 17 00:00:00 2001
From: Andreas Zwinkau <Andreas.Zwinkau@etas.com>
Date: Wed, 5 Aug 2026 13:06:19 +0200
Subject: [PATCH 2/2] feat: reusable py_binary made public

---
 src/extensions/score_metamodel/docs/BUILD | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/extensions/score_metamodel/docs/BUILD b/src/extensions/score_metamodel/docs/BUILD
index 30b89e9a6..389c9a57d 100644
--- a/src/extensions/score_metamodel/docs/BUILD
+++ b/src/extensions/score_metamodel/docs/BUILD
@@ -31,7 +31,7 @@ py_binary(
     srcs = ["generate_metamodel_rst.py"],
     main = "generate_metamodel_rst.py",
     deps = all_requirements,
-    visibility = ["//visibility:private"],
+    visibility = ["//visibility:public"], # public to be reuseable for other metamodels
 )
 
 docs_bundle(