From 7f2641cd074dee6561421feacc2557ef1d3ce4dd Mon Sep 17 00:00:00 2001 From: Derek Cormier Date: Wed, 2 Mar 2022 16:00:53 -0800 Subject: [PATCH] reimplement stardoc_with_diff_test to use write_source_files --- docs/BUILD.bazel | 19 ++++---- docs/docs.md | 16 +++---- docs/jq.md | 0 docs/write_source_files.md | 2 +- lib/private/BUILD.bazel | 1 + lib/private/docs.bzl | 71 +++++++++++++----------------- lib/private/write_source_files.bzl | 6 +-- lib/write_source_files.bzl | 2 +- 8 files changed, 53 insertions(+), 64 deletions(-) mode change 100755 => 100644 docs/jq.md mode change 100755 => 100644 docs/write_source_files.md diff --git a/docs/BUILD.bazel b/docs/BUILD.bazel index 96379c25a..16f17002e 100644 --- a/docs/BUILD.bazel +++ b/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", ) diff --git a/docs/docs.md b/docs/docs.md index 8cab2614c..793db71ff 100644 --- a/docs/docs.md +++ b/docs/docs.md @@ -7,11 +7,11 @@ Public API for docs helpers ## stardoc_with_diff_test 
-stardoc_with_diff_test(bzl_library_target, out_label, aspect_template, func_template,
-                       header_template, provider_template, rule_template)
+stardoc_with_diff_test(name, bzl_library_target, aspect_template, func_template, header_template,
+                       provider_template, rule_template, suggested_update_target)
-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 | | :------------- | :------------- | :------------- | +| 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 | | bzl_library_target | the label of the bzl_library target to generate documentation for | none | -| out_label | the label of the output MD file | none | | aspect_template | the label or path to the Velocity aspect template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/aspect.vm" | | func_template | the label or path to the Velocity function/macro template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/func.vm" | | header_template | the label or path to the Velocity header template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/header.vm" | | provider_template | the label or path to the Velocity provider template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/provider.vm" | | rule_template | the label or path to the Velocity rule template to use with stardoc | "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm" | +| 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)) | "//docs:update" | @@ -35,10 +36,10 @@ This is helpful for minimizing boilerplate in repos wih lots of stardoc targets. ## update_docs 
-update_docs(name, docs_folder)
+update_docs(name)
-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 | | :------------- | :------------- | :------------- | -| name | the name of the sh_binary target | "update" | -| docs_folder | the name of the folder containing the doc files in the local source tree | "docs" | +| name | the name of executable target | "update" | diff --git a/docs/jq.md b/docs/jq.md old mode 100755 new mode 100644 diff --git a/docs/write_source_files.md b/docs/write_source_files.md old mode 100755 new mode 100644 index 906af4a49..79df273f6 --- a/docs/write_source_files.md +++ b/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 | | :------------- | :------------- | :------------- | | name | Name of the executable target that creates or updates the source file | none | -| 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 | +| 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. | {} | | additional_update_targets | (Optional) List of other write_source_files targets to update in the same run | [] | | suggested_update_target | (Optional) Label of the write_source_files target to suggest running when files are out of date | None | | kwargs | Other common named parameters such as tags or visibility | none | diff --git a/lib/private/BUILD.bazel b/lib/private/BUILD.bazel index ef0d2fdc4..8c9f6aa07 100644 --- a/lib/private/BUILD.bazel +++ b/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", diff --git a/lib/private/docs.bzl b/lib/private/docs.bzl index f5fad1c29..4ac00dbf7 100644 --- a/lib/private/docs.bzl +++ b/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("@bazel_skylib//rules:diff_test.bzl", "diff_test") +load("//lib:write_source_files.bzl", "write_source_files") 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"): - """Creates a stardoc target coupled with a `diff_test` for a given `bzl_library`. + rule_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm", + 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"), - out = out_file.replace(".md", "-docgen.md"), + name = stardoc_label, + 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 - diff_test( - name = out_file.replace("/", "_").replace(".md", "-difftest"), - failure_message = "Please run \"bazel run //docs:update\"", - # Source file - file1 = out_label, - # Output from stardoc rule above - file2 = out_file.replace(".md", "-docgen.md"), + write_source_files( + name = name, + suggested_update_target = suggested_update_target, + files = { + out_file: ":" + stardoc_label, + }, ) -def update_docs( - name = "update", - docs_folder = "docs"): - """Creates a `sh_binary` target which copies over generated doc files to the local source tree. +def update_docs(name = "update"): + """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: @@ -70,29 +69,19 @@ def update_docs( ``` Args: - name: the name of the `sh_binary` target - docs_folder: the name of the folder containing the doc files in the local source tree + name: the name of executable target """ - 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"] - if doc_gen.startswith(":"): - doc_gen = doc_gen[1:] - doc_dest = doc_gen.replace("-docgen.md", ".md") - data.append(doc_gen) - content.append("cp -fv bazel-bin/{0}/{1} {2}".format(docs_folder, doc_gen, doc_dest)) - - update_script = name + ".sh" - write_file( - name = "gen_" + name, - out = update_script, - content = content, - ) + 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)) - native.sh_binary( + write_source_files( name = name, - srcs = [update_script], - data = data, + additional_update_targets = update_labels, ) diff --git a/lib/private/write_source_files.bzl b/lib/private/write_source_files.bzl index 98b59e0a3..bdc19a2ee 100644 --- a/lib/private/write_source_files.bzl +++ b/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), - "out_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 = 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 diff --git a/lib/write_source_files.bzl b/lib/write_source_files.bzl index 744610ed4..aafa5650a 100644 --- a/lib/write_source_files.bzl +++ b/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: