From 93d8f702272a29896b4938ef42f17a49dafdbd1c Mon Sep 17 00:00:00 2001 From: Alexander Lanin Date: Tue, 1 Sep 2026 13:51:52 +0200 Subject: [PATCH] docs: do not use literalinclude for now --- BUILD | 6 -- docs/how-to/bundles/examples.rst | 60 +++++++++++++++---- .../scenarios/data_files_runfiles/BUILD | 6 -- .../docs_bzl/scenarios/external_bundle/BUILD | 6 -- .../docs_bzl/scenarios/nested_bundles/BUILD | 6 -- 5 files changed, 48 insertions(+), 36 deletions(-) diff --git a/BUILD b/BUILD index d28698186..8a002a5ab 100644 --- a/BUILD +++ b/BUILD @@ -25,12 +25,6 @@ docs( external_needs = [ "@score_process_description//:needs_json_file", ], - data = [ - # These scenario BUILD files are used by literalinclude examples. - "//src/tests/docs_bzl/scenarios/nested_bundles:nested_bundle_build", - "//src/tests/docs_bzl/scenarios/data_files_runfiles:generated_data_build", - "//src/tests/docs_bzl/scenarios/external_bundle:external_bundle_build", - ], bundles = [ { "bundle": "//src/extensions/docs:extensions", diff --git a/docs/how-to/bundles/examples.rst b/docs/how-to/bundles/examples.rst index 5dcbe2ff9..3c70beeeb 100644 --- a/docs/how-to/bundles/examples.rst +++ b/docs/how-to/bundles/examples.rst @@ -30,10 +30,18 @@ consuming project chooses where the assembled bundle appears. The tested parent bundle composes the child like this: -.. literalinclude:: ../../../src/tests/docs_bzl/scenarios/nested_bundles/BUILD - :language: starlark - :start-after: BEGIN docs-bundle-howto: parent-composition - :end-before: END docs-bundle-howto: parent-composition +.. code-block:: starlark + + docs_bundle( + name = "parent", + source_dir = "parent", + bundles = [{ + "bundle": ":child", + "mount_at": "child", + }], + data = [":generated_doc_output"], + visibility = ["//visibility:public"], + ) See the `complete nested-bundles fixture on GitHub `_. @@ -50,10 +58,32 @@ Use a data-only bundle when a build action produces the documentation rather than a source-tree ``.rst`` file. It has no ``source_dir``; its generated files are the bundle's complete payload. You can generate and mount a page like this: -.. literalinclude:: ../../../src/tests/docs_bzl/scenarios/data_files_runfiles/BUILD - :language: starlark - :start-after: BEGIN docs-bundle-howto: generated-data - :end-before: END docs-bundle-howto: generated-data +.. code-block:: starlark + + genrule( + name = "generated_page", + srcs = [], + outs = ["generated/index.rst"], + cmd = """echo 'Generated Data Page + ===================' > $@""", + ) + + # Pure-data bundle: the genrule output lives in ``bazel-out/``, not the tree. + docs_bundle( + name = "data_bundle", + data = [":generated_page"], + entry_doc = "index", + visibility = ["//visibility:public"], + ) + + docs( + source_dir = "docs", + bundles = [{ + "bundle": ":data_bundle", + "mount_at": "data_test", + "attach_to": "index", + }], + ) See the `complete generated-data fixture on GitHub `_. @@ -70,10 +100,16 @@ Every project using ``docs()`` exposes its own documentation as a ``:docs_bundle`` target. The external-bundle test fixture mounts that target like this: -.. literalinclude:: ../../../src/tests/docs_bzl/scenarios/external_bundle/BUILD - :language: starlark - :start-after: BEGIN docs-bundle-howto: external-bundle - :end-before: END docs-bundle-howto: external-bundle +.. code-block:: starlark + + docs( + source_dir = "host_docs", + test_sources = ["src/tests/docs_bzl/scenarios/external_bundle"], + bundles = [{ + "bundle": "@score_process_description//:docs_bundle", + "mount_at": "process", + }], + ) See the `complete external-bundle fixture on GitHub `_. diff --git a/src/tests/docs_bzl/scenarios/data_files_runfiles/BUILD b/src/tests/docs_bzl/scenarios/data_files_runfiles/BUILD index 2743758e8..c03222455 100644 --- a/src/tests/docs_bzl/scenarios/data_files_runfiles/BUILD +++ b/src/tests/docs_bzl/scenarios/data_files_runfiles/BUILD @@ -18,12 +18,6 @@ load("//:docs.bzl", "docs", "docs_bundle") -filegroup( - name = "generated_data_build", - srcs = ["BUILD"], - visibility = ["//visibility:public"], -) - # Emit into a ``generated/`` subdirectory (as the real metamodel bundle does) # so the resolved mount directory contains only the genrule output and not the # sibling ``docs.runfiles/`` tree. diff --git a/src/tests/docs_bzl/scenarios/external_bundle/BUILD b/src/tests/docs_bzl/scenarios/external_bundle/BUILD index f0f261207..2a1f85c6f 100644 --- a/src/tests/docs_bzl/scenarios/external_bundle/BUILD +++ b/src/tests/docs_bzl/scenarios/external_bundle/BUILD @@ -13,12 +13,6 @@ load("//:docs.bzl", "docs") -filegroup( - name = "external_bundle_build", - srcs = ["BUILD"], - visibility = ["//visibility:public"], -) - # This fixture exercises the public Bzlmod contract. In particular, the # sandboxed :needs_json target must be able to walk an external bundle rather # than silently omitting it. diff --git a/src/tests/docs_bzl/scenarios/nested_bundles/BUILD b/src/tests/docs_bzl/scenarios/nested_bundles/BUILD index 8b767c694..af393c3ec 100644 --- a/src/tests/docs_bzl/scenarios/nested_bundles/BUILD +++ b/src/tests/docs_bzl/scenarios/nested_bundles/BUILD @@ -15,12 +15,6 @@ load("//:bzl/mount_rules.bzl", "create_mounts_manifest") load("//:docs.bzl", "docs", "docs_bundle") load("@aspect_rules_py//py:defs.bzl", "py_binary") -filegroup( - name = "nested_bundle_build", - srcs = ["BUILD"], - visibility = ["//visibility:public"], -) - docs_bundle( name = "child", source_dir = "child",