fix: set correct suggested_update_target for write_source_files macros with multiple files (#120)

Author: gregmagolan

docs/docs.md

@@ -1,45 +1,32 @@
 "Helpers for generating stardoc documentation"
 
-load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
+load("@io_bazel_stardoc//stardoc:stardoc.bzl", _stardoc = "stardoc")
 load("//lib:write_source_files.bzl", "write_source_files")
 
 def stardoc_with_diff_test(
         name,
         bzl_library_target,
-        suggested_update_target = "//docs:update",
         **kwargs):
-    """Creates a stardoc target, diff test, and an executable to rule to write the generated doc to the source tree and test that it's up to date.
+    """Creates a stardoc target that can be auto-detected by update_docs to write the generated doc to the source tree and test that it's up to date.
 
     This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.
 
     Args:
         name: the name of the stardoc file to be written to the current source directory (.md will be appended to the name). Call bazel run on this target to update the file.
         bzl_library_target: the label of the `bzl_library` target to generate documentation for
-        suggested_update_target: the target suggested to be run when a doc is out of date (should be the label for [update_docs](#update_docs))
         **kwargs: additional attributes passed to the stardoc() rule, such as for overriding the templates
     """
 
-    stardoc_label = name + "-docgen"
-    out_file = name + ".md"
-
     # Generate MD from .bzl
-    stardoc(
-        name = stardoc_label,
+    _stardoc(
+        name = name,
         out = name + "-docgen.md",
         input = bzl_library_target + ".bzl",
         deps = [bzl_library_target],
         tags = ["package:" + native.package_name()],  # Tag the package name which will help us reconstruct the write_source_files label in update_docs
         **kwargs
     )
 
-    write_source_files(
-        name = name,
-        suggested_update_target = suggested_update_target,
-        files = {
-            out_file: ":" + stardoc_label,
-        },
-    )
-
 def update_docs(name = "update"):
     """Stamps an executable run for writing all stardocs declared with stardoc_with_diff_test to the source tree.
 
@@ -60,16 +47,17 @@ def update_docs(name = "update"):
         name: the name of executable target
     """
 
-    update_labels = []
+    update_files = {}
     for r in native.existing_rules().values():
         if r["kind"] == "stardoc":
             for tag in r["tags"]:
                 if tag.startswith("package:"):
                     stardoc_name = r["name"]
-                    write_source_files_name = stardoc_name[:-len("-docgen")]
-                    update_labels.append("//%s:%s" % (tag[len("package:"):], write_source_files_name))
+                    source_file_name = stardoc_name + ".md"
+                    generated_file_name = stardoc_name + "-docgen.md"
+                    update_files[source_file_name] = generated_file_name
 
     write_source_files(
         name = name,
-        additional_update_targets = update_labels,
+        files = update_files,
     )

lib/private/docs.bzl

@@ -96,19 +96,22 @@ def write_source_files(
     for i, pair in enumerate(files.items()):
         out_file, in_file = pair
 
+        this_suggested_update_target = suggested_update_target
         if single_update_target:
             update_target_name = name
         else:
             update_target_name = "%s_%d" % (name, i)
             update_targets.append(update_target_name)
+            if not this_suggested_update_target:
+                this_suggested_update_target = name
 
         # Runnable target that writes to the out file to the source tree
         _write_source_file(
             name = update_target_name,
             in_file = in_file,
             out_file = out_file,
             additional_update_targets = additional_update_targets if single_update_target else [],
-            suggested_update_target = suggested_update_target,
+            suggested_update_target = this_suggested_update_target,
             diff_test = diff_test,
             **kwargs
         )