chore: Remove *_build_test targets from sphinx_docs (#2645) (#2650)

255 · rickeylev · web-flow · commit 0fa6667de443 · 2025-03-06T23:12:31.000Z
Remove implicit `build_test`s from `sphinx_docs` targets. Instead, users
can decide whether or not to add `build_tests` for docs. This also keeps
`sphinx_docs` builds out of `bazel test //...`, which may not be
desirable.

Add `build_test`s to cover in-tree `sphinx_docs` targets. Rename the
existing `build_test` for `//sphinxdocs/tests/sphinx_docs:docs` to match
the new targets.

Also, tag the `sphinx_docs` `*.run` and `*.serve` targets as `"manual"`
so they are excluded from wildcards. These are only needed for
interactive development.

---------

Co-authored-by: Richard Levasseur &lt;richardlev@gmail.com&gt;
diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
@@ -13,6 +13,7 @@
 # limitations under the License.
 
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_skylib//rules:build_test.bzl", "build_test")
 load("@dev_pip//:requirements.bzl", "requirement")
 load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED")  # buildifier: disable=bzl-visibility
 load("//python/private:util.bzl", "IS_BAZEL_7_OR_HIGHER")  # buildifier: disable=bzl-visibility
@@ -77,6 +78,11 @@ sphinx_docs(
     ],
 )
 
+build_test(
+    name = "docs_build_test",
+    targets = [":docs"],
+)
+
 sphinx_stardocs(
     name = "bzl_api_docs",
     srcs = [
diff --git a/sphinxdocs/private/sphinx.bzl b/sphinxdocs/private/sphinx.bzl
@@ -15,7 +15,6 @@
 """Implementation of sphinx rules."""
 
 load("@bazel_skylib//lib:paths.bzl", "paths")
-load("@bazel_skylib//rules:build_test.bzl", "build_test")
 load("@bazel_skylib//rules:common_settings.bzl", "BuildSettingInfo")
 load("//python:py_binary.bzl", "py_binary")
 load("//python/private:util.bzl", "add_tag", "copy_propagating_kwargs")  # buildifier: disable=bzl-visibility
@@ -177,6 +176,9 @@ def sphinx_docs(
         **common_kwargs
     )
 
+    common_kwargs_with_manual_tag = dict(common_kwargs)
+    common_kwargs_with_manual_tag["tags"] = list(common_kwargs.get("tags") or []) + ["manual"]
+
     py_binary(
         name = name + ".serve",
         srcs = [_SPHINX_SERVE_MAIN_SRC],
@@ -185,18 +187,12 @@ def sphinx_docs(
         args = [
             "$(execpath {})".format(html_name),
         ],
-        **common_kwargs
+        **common_kwargs_with_manual_tag
     )
     sphinx_run(
         name = name + ".run",
         docs = name,
-        **common_kwargs
-    )
-
-    build_test(
-        name = name + "_build_test",
-        targets = [name],
-        **kwargs  # kwargs used to pick up target_compatible_with
+        **common_kwargs_with_manual_tag
     )
 
 def _sphinx_docs_impl(ctx):
diff --git a/sphinxdocs/tests/sphinx_docs/BUILD.bazel b/sphinxdocs/tests/sphinx_docs/BUILD.bazel
@@ -40,6 +40,6 @@ sphinx_build_binary(
 )
 
 build_test(
-    name = "build_tests",
+    name = "docs_build_test",
     targets = [":docs"],
 )
diff --git a/sphinxdocs/tests/sphinx_stardoc/BUILD.bazel b/sphinxdocs/tests/sphinx_stardoc/BUILD.bazel
@@ -1,4 +1,5 @@
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
+load("@bazel_skylib//rules:build_test.bzl", "build_test")
 load("//python:py_test.bzl", "py_test")
 load("//python/private:util.bzl", "IS_BAZEL_7_OR_HIGHER")  # buildifier: disable=bzl-visibility
 load("//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
@@ -40,6 +41,11 @@ sphinx_docs(
     ],
 )
 
+build_test(
+    name = "docs_build_test",
+    targets = [":docs"],
+)
+
 sphinx_stardocs(
     name = "simple_bzl_docs",
     srcs = [
