reimplement stardoc_with_diff_test to use write_source_files

docs/BUILD.bazel

@@ -3,52 +3,51 @@
 load("//lib:docs.bzl", "stardoc_with_diff_test", "update_docs")
 
 stardoc_with_diff_test(
+    name = "copy_to_directory",
     bzl_library_target = "//lib:copy_to_directory",
-    out_label = "//docs:copy_to_directory.md",
 )
 
 stardoc_with_diff_test(
+    name = "docs",
     bzl_library_target = "//lib:docs",
-    out_label = "//docs:docs.md",
 )
 
 stardoc_with_diff_test(
+    name = "expand_make_vars",
     bzl_library_target = "//lib:expand_make_vars",
-    out_label = "//docs:expand_make_vars.md",
 )
 
 stardoc_with_diff_test(
+    name = "params_file",
     bzl_library_target = "//lib:params_file",
     func_template = "//docs/templates:func_html.vm",
-    out_label = "//docs:params_file.md",
 )
 
 stardoc_with_diff_test(
+    name = "paths",
     bzl_library_target = "//lib:paths",
-    out_label = "//docs:paths.md",
 )
 
 stardoc_with_diff_test(
+    name = "utils",
     bzl_library_target = "//lib:utils",
-    out_label = "//docs:utils.md",
 )
 
 stardoc_with_diff_test(
+    name = "jq",
     bzl_library_target = "//lib:jq",
-    out_label = "//docs:jq.md",
 )
 
 stardoc_with_diff_test(
+    name = "write_source_files",
     bzl_library_target = "//lib:write_source_files",
-    out_label = "//docs:write_source_files.md",
 )
 
 stardoc_with_diff_test(
+    name = "directory_path",
     bzl_library_target = "//lib:directory_path",
-    out_label = "//docs:directory_path.md",
 )
 
 update_docs(
     name = "update",
-    docs_folder = "docs",
 )

docs/docs.md

@@ -7,11 +7,11 @@ Public API for docs helpers
 ## stardoc_with_diff_test
 
 <pre>
-stardoc_with_diff_test(<a href="#stardoc_with_diff_test-bzl_library_target">bzl_library_target</a>, <a href="#stardoc_with_diff_test-out_label">out_label</a>, <a href="#stardoc_with_diff_test-aspect_template">aspect_template</a>, <a href="#stardoc_with_diff_test-func_template">func_template</a>,
+stardoc_with_diff_test(<a href="#stardoc_with_diff_test-name">name</a>, <a href="#stardoc_with_diff_test-bzl_library_target">bzl_library_target</a>, <a href="#stardoc_with_diff_test-aspect_template">aspect_template</a>, <a href="#stardoc_with_diff_test-func_template">func_template</a>, <a href="#stardoc_with_diff_test-header_template">header_template</a>,
-                       <a href="#stardoc_with_diff_test-header_template">header_template</a>, <a href="#stardoc_with_diff_test-provider_template">provider_template</a>, <a href="#stardoc_with_diff_test-rule_template">rule_template</a>)
+                       <a href="#stardoc_with_diff_test-provider_template">provider_template</a>, <a href="#stardoc_with_diff_test-rule_template">rule_template</a>, <a href="#stardoc_with_diff_test-suggested_update_target">suggested_update_target</a>)
 </pre>
 
-Creates a stardoc target coupled with a `diff_test` for a given `bzl_library`.
+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.
 
 This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.
 
@@ -21,13 +21,14 @@ This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
+| <a id="stardoc_with_diff_test-name"></a>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.   |  none |
 | <a id="stardoc_with_diff_test-bzl_library_target"></a>bzl_library_target |  the label of the <code>bzl_library</code> target to generate documentation for   |  none |
-| <a id="stardoc_with_diff_test-out_label"></a>out_label |  the label of the output MD file   |  none |
 | <a id="stardoc_with_diff_test-aspect_template"></a>aspect_template |  the label or path to the Velocity aspect template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm"</code> |
 | <a id="stardoc_with_diff_test-func_template"></a>func_template |  the label or path to the Velocity function/macro template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm"</code> |
 | <a id="stardoc_with_diff_test-header_template"></a>header_template |  the label or path to the Velocity header template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm"</code> |
 | <a id="stardoc_with_diff_test-provider_template"></a>provider_template |  the label or path to the Velocity provider template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm"</code> |
 | <a id="stardoc_with_diff_test-rule_template"></a>rule_template |  the label or path to the Velocity rule template to use with stardoc   |  <code>"@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm"</code> |
+| <a id="stardoc_with_diff_test-suggested_update_target"></a>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))   |  <code>"//docs:update"</code> |
 
 
 <a id="#update_docs"></a>
@@ -35,10 +36,10 @@ This is helpful for minimizing boilerplate in repos wih lots of stardoc targets.
 ## update_docs
 
 <pre>
-update_docs(<a href="#update_docs-name">name</a>, <a href="#update_docs-docs_folder">docs_folder</a>)
+update_docs(<a href="#update_docs-name">name</a>)
 </pre>
 
-Creates a `sh_binary` target which copies over generated doc files to the local source tree.
+Stamps an executable run for writing all stardocs declared with stardoc_with_diff_test to the source tree.
 
 This is to be used in tandem with `stardoc_with_diff_test()` to produce a convenient workflow
 for generating, testing, and updating all doc files as follows:
@@ -59,7 +60,6 @@ bazel build //docs/... && bazel test //docs/... && bazel run //docs:update
 
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
-| <a id="update_docs-name"></a>name |  the name of the <code>sh_binary</code> target   |  <code>"update"</code> |
+| <a id="update_docs-name"></a>name |  the name of executable target   |  <code>"update"</code> |
-| <a id="update_docs-docs_folder"></a>docs_folder |  the name of the folder containing the doc files in the local source tree   |  <code>"docs"</code> |
 
 

docs/write_source_files.md

@@ -86,7 +86,7 @@ If you have many sources that you want to update as a group, we recommend wrappi
 | Name  | Description | Default Value |
 | :------------- | :------------- | :------------- |
 | <a id="write_source_files-name"></a>name |  Name of the executable target that creates or updates the source file   |  none |
-| <a id="write_source_files-files"></a>files |  A dict where the keys are source files or folders to write to and the values are labels pointing to the desired content. Sources must be within the same bazel package as the target.   |  none |
+| <a id="write_source_files-files"></a>files |  A dict where the keys are source files or folders to write to and the values are labels pointing to the desired content. Sources must be within the same bazel package as the target.   |  <code>{}</code> |
 | <a id="write_source_files-additional_update_targets"></a>additional_update_targets |  (Optional) List of other write_source_files targets to update in the same run   |  <code>[]</code> |
 | <a id="write_source_files-suggested_update_target"></a>suggested_update_target |  (Optional) Label of the write_source_files target to suggest running when files are out of date   |  <code>None</code> |
 | <a id="write_source_files-kwargs"></a>kwargs |  Other common named parameters such as <code>tags</code> or <code>visibility</code>   |  none |

lib/private/BUILD.bazel

@@ -35,6 +35,7 @@ bzl_library(
     srcs = ["docs.bzl"],
     visibility = ["//lib:__subpackages__"],
     deps = [
+        "//lib:write_source_files",
         "@bazel_skylib//rules:diff_test",
         "@bazel_skylib//rules:write_file",
         "@io_bazel_stardoc//stardoc:stardoc_lib",

lib/private/docs.bzl

@@ -1,37 +1,39 @@
 "Helpers for generating stardoc documentation"
 
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
-load("@bazel_skylib//rules:write_file.bzl", "write_file")
+load("//lib:write_source_files.bzl", "write_source_files")
-load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
 
 def stardoc_with_diff_test(
+        name,
         bzl_library_target,
-        out_label,
         aspect_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm",
         func_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm",
         header_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm",
         provider_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm",
-        rule_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm"):
+        rule_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm",
-    """Creates a stardoc target coupled with a `diff_test` for a given `bzl_library`.
+        suggested_update_target = "//docs:update"):
+    """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.
 
     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
-        out_label: the label of the output MD file
         aspect_template: the label or path to the Velocity aspect template to use with stardoc
         func_template: the label or path to the Velocity function/macro template to use with stardoc
         header_template: the label or path to the Velocity header template to use with stardoc
         provider_template: the label or path to the Velocity provider template to use with stardoc
         rule_template: the label or path to the Velocity rule template to use with stardoc
+        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))
     """
 
-    out_file = out_label.replace("//", "").replace(":", "/")
+    stardoc_label = name + "-docgen"
+    out_file = name + ".md"
 
     # Generate MD from .bzl
     stardoc(
-        name = out_file.replace("/", "_").replace(".md", "-docgen"),
+        name = stardoc_label,
-        out = out_file.replace(".md", "-docgen.md"),
+        out = name + "-docgen.md",
         input = bzl_library_target + ".bzl",
         deps = [bzl_library_target],
         aspect_template = aspect_template,
@@ -39,22 +41,19 @@ def stardoc_with_diff_test(
         header_template = header_template,
         provider_template = provider_template,
         rule_template = rule_template,
+        tags = ["package:" + native.package_name()],  # Tag the package name which will help us reconstruct the write_source_files label in update_docs
     )
 
-    # Ensure that the generated MD has been updated in the local source tree
+    write_source_files(
-    diff_test(
+        name = name,
-        name = out_file.replace("/", "_").replace(".md", "-difftest"),
+        suggested_update_target = suggested_update_target,
-        failure_message = "Please run \"bazel run //docs:update\"",
+        files = {
-        # Source file
+            out_file: ":" + stardoc_label,
-        file1 = out_label,
+        },
-        # Output from stardoc rule above
-        file2 = out_file.replace(".md", "-docgen.md"),
     )
 
-def update_docs(
+def update_docs(name = "update"):
-        name = "update",
+    """Stamps an executable run for writing all stardocs declared with stardoc_with_diff_test to the source tree.
-        docs_folder = "docs"):
-    """Creates a `sh_binary` target which copies over generated doc files to the local source tree.
 
     This is to be used in tandem with `stardoc_with_diff_test()` to produce a convenient workflow
     for generating, testing, and updating all doc files as follows:
@@ -70,29 +69,19 @@ def update_docs(
     ```
 
     Args:
-        name: the name of the `sh_binary` target
+        name: the name of executable target
-        docs_folder: the name of the folder containing the doc files in the local source tree
     """
-    content = ["#!/usr/bin/env bash", "cd ${BUILD_WORKSPACE_DIRECTORY}"]
+
-    data = []
+    update_labels = []
     for r in native.existing_rules().values():
         if r["kind"] == "stardoc":
-            doc_gen = r["out"]
+            for tag in r["tags"]:
-            if doc_gen.startswith(":"):
+                if tag.startswith("package:"):
-                doc_gen = doc_gen[1:]
+                    stardoc_name = r["name"]
-            doc_dest = doc_gen.replace("-docgen.md", ".md")
+                    write_source_files_name = stardoc_name[:-len("-docgen")]
-            data.append(doc_gen)
+                    update_labels.append("//%s:%s" % (tag[len("package:"):], write_source_files_name))
-            content.append("cp -fv bazel-bin/{0}/{1} {2}".format(docs_folder, doc_gen, doc_dest))
 
-    update_script = name + ".sh"
+    write_source_files(
-    write_file(
-        name = "gen_" + name,
-        out = update_script,
-        content = content,
-    )
-
-    native.sh_binary(
         name = name,
-        srcs = [update_script],
+        additional_update_targets = update_labels,
-        data = data,
     )

lib/private/write_source_files.bzl

@@ -10,8 +10,8 @@ _WriteSourceFilesInfo = provider(
 )
 
 _write_source_files_attrs = {
-    "in_files": attr.label_list(allow_files = True, allow_empty = False, mandatory = False),
+    "in_files": attr.label_list(allow_files = True, allow_empty = True, mandatory = False),
-    "out_files": attr.label_list(allow_files = True, allow_empty = False, mandatory = False),
+    "out_files": attr.label_list(allow_files = True, allow_empty = True, mandatory = False),
     "additional_update_targets": attr.label_list(allow_files = False, providers = [_WriteSourceFilesInfo], mandatory = False),
     "is_windows": attr.bool(mandatory = True),
 }
@@ -100,7 +100,7 @@ if exist "%in%\\*" (
 )
 """.format(in_file = ctx.files.in_files[i].short_path.replace("/", "\\"), out_file = ctx.files.out_files[i].short_path.replace("/", "\\"))
         for i in range(len(ctx.attr.in_files))
-    ])  + """
+    ]) + """
 cd %runfiles_dir%
 
 @rem Run the update scripts for all write_source_file deps

lib/write_source_files.bzl

@@ -11,7 +11,7 @@ _write_source_files = rule(
     executable = True,
 )
 
-def write_source_files(name, files, additional_update_targets = [], suggested_update_target = None, **kwargs):
+def write_source_files(name, files = {}, additional_update_targets = [], suggested_update_target = None, **kwargs):
     """Write to one or more files or folders in the source tree. Stamp out tests that ensure the sources exist and are up to date.
 
     Usage: