From 235e733c78eb3800ca675e1ca36032a62af612b9 Mon Sep 17 00:00:00 2001
From: Alex Eagle <alex@aspect.dev>
Date: Sun, 11 May 2025 21:22:19 -0700
Subject: [PATCH] feat: generate doc_extract targets

Allows bzl_library targets to produce documentation without needing to load stardoc or add additional targets.
Note, it would be better to do this with an aspect that visits the bzl_library graph, but the starlark_doc_extract rule is in Bazel java core, and so we cannot spawn actions using its Java code. It needs a main() entry point.

Use a config_setting to make this opt-in, so we don't generate so many targets all the time.
---
 BUILD           | 14 ++++++++++++++
 bzl_library.bzl | 15 ++++++++++++++-
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/BUILD b/BUILD
index 635f9538..10df9b4a 100644
--- a/BUILD
+++ b/BUILD
@@ -1,4 +1,5 @@
 load("@rules_license//rules:license.bzl", "license")
+load("//rules:common_settings.bzl", "bool_flag")
 load("//:bzl_library.bzl", "bzl_library")
 
 package(
@@ -95,3 +96,16 @@ filegroup(
         "//toolchains/unittest:distribution",
     ] + glob(["*.bzl"]),
 )
+
+bool_flag(
+    name = "extract_docs",
+    build_setting_default = False,
+    visibility = ["//visibility:public"],
+)
+
+config_setting(
+    name = "extract_docs_flag",
+    flag_values = {
+        ":extract_docs": "true",
+    },
+)
diff --git a/bzl_library.bzl b/bzl_library.bzl
index d6dbf817..c59a59e4 100644
--- a/bzl_library.bzl
+++ b/bzl_library.bzl
@@ -23,7 +23,7 @@ load(
 
 StarlarkLibraryInfo = _StarlarkLibraryInfo
 
-def bzl_library(name, **kwargs):
+def bzl_library(name, srcs = [], deps = [], **kwargs):
     """Wrapper for bzl_library.
 
     Args:
@@ -38,9 +38,22 @@ def bzl_library(name, **kwargs):
     _ = kwargs.pop("target_compatible_with", None)
     _bzl_library(
         name = name,
+        srcs = srcs,
+        deps = deps,
         compatible_with = [],
         exec_compatible_with = [],
         features = [],
         target_compatible_with = [],
         **kwargs
     )
+    enable_doc_extract = select({
+        Label("//:extract_docs_flag"): hasattr(native, "starlark_doc_extract"),
+        "//conditions:default": False,
+    })
+    if enable_doc_extract:
+        for i, src in enumerate(srcs):
+            native.starlark_doc_extract(
+                name = "{}.doc_extract{}".format(name, i if i > 0 else ""),
+                src = src,
+                deps = deps,
+            )