From 98b810bee8b050a3c78b0237f62642b4c0b94605 Mon Sep 17 00:00:00 2001
From: Wyatt Hepler <hepler@google.com>
Date: Thu, 6 Mar 2025 19:10:18 +0000
Subject: [PATCH 1/2] chore: Remove *_build_test targets from sphinx_docs
 (#2645)

Remove implicit build_tests 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_tests 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.
---
 docs/BUILD.bazel                            |  6 ++++++
 sphinxdocs/private/sphinx.bzl               | 14 +++++---------
 sphinxdocs/tests/sphinx_docs/BUILD.bazel    |  2 +-
 sphinxdocs/tests/sphinx_stardoc/BUILD.bazel |  6 ++++++
 4 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel
index ea386f114a..0c07002a01 100644
--- 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
index 7ec35f9ab4..ec0dd3772b 100644
--- 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.setdefault("tags", []).append("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
index 1a05db0ea3..f9c82967c1 100644
--- 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
index 60a5e8d766..e3a68ea225 100644
--- 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 = [

From e764d599a3cfd6158dd8ce91184309eff8f6a66a Mon Sep 17 00:00:00 2001
From: Richard Levasseur <richardlev@gmail.com>
Date: Thu, 6 Mar 2025 12:03:52 -0800
Subject: [PATCH 2/2] copy tags to avoid modifying common_kwargs tags

---
 sphinxdocs/private/sphinx.bzl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/sphinxdocs/private/sphinx.bzl b/sphinxdocs/private/sphinx.bzl
index ec0dd3772b..8d19d87052 100644
--- a/sphinxdocs/private/sphinx.bzl
+++ b/sphinxdocs/private/sphinx.bzl
@@ -177,7 +177,7 @@ def sphinx_docs(
     )
 
     common_kwargs_with_manual_tag = dict(common_kwargs)
-    common_kwargs_with_manual_tag.setdefault("tags", []).append("manual")
+    common_kwargs_with_manual_tag["tags"] = list(common_kwargs.get("tags") or []) + ["manual"]
 
     py_binary(
         name = name + ".serve",