feat: how-to for generated docs

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.

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

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(