diff options
Diffstat (limited to 'docs/doc_helpers.bzl')
-rw-r--r-- | docs/doc_helpers.bzl | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/docs/doc_helpers.bzl b/docs/doc_helpers.bzl new file mode 100644 index 00000000..dbec0d5f --- /dev/null +++ b/docs/doc_helpers.bzl @@ -0,0 +1,84 @@ +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") + +def stardoc_with_diff_test( + bzl_library_target, + out_label, + 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. + + This is helpful for minimizing boilerplate when lots of stardoc targets are to be generated. + + Args: + bzl_library_target: the label of the bzl_library target to generate documentation for + out_label: the label of the output MD file + rule_template: the label or path to the Velocity rule template to use with stardoc + """ + + out_file = out_label.replace("//", "").replace(":", "/") + + # Generate MD from .bzl + stardoc( + name = out_file.replace("/", "_").replace(".md", "-docgen"), + out = out_file.replace(".md", "-docgen.md"), + input = bzl_library_target + ".bzl", + rule_template = rule_template, + deps = [bzl_library_target], + ) + + # 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"), + ) + +def update_docs( + name = "update", + 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: + + ``` bash + bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update + ``` + + eg. + + ``` bash + bazel build //docs/... && bazel test //docs/... && bazel run //docs:update + ``` + + 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 + """ + content = ["#!/usr/bin/env bash", "cd ${BUILD_WORKSPACE_DIRECTORY}"] + data = [] + 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, + ) + + native.sh_binary( + name = name, + srcs = [update_script], + data = data, + ) |