1load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") 2load("@bazel_skylib//rules:write_file.bzl", "write_file") 3load("@bazel_skylib//rules:diff_test.bzl", "diff_test") 4 5def stardoc_with_diff_test( 6 bzl_library_target, 7 out_label, 8 rule_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm"): 9 """Creates a stardoc target coupled with a diff_test for a given bzl_library. 10 11 This is helpful for minimizing boilerplate when lots of stardoc targets are to be generated. 12 13 Args: 14 bzl_library_target: the label of the bzl_library target to generate documentation for 15 out_label: the label of the output MD file 16 rule_template: the label or path to the Velocity rule template to use with stardoc 17 """ 18 19 out_file = out_label.replace("//", "").replace(":", "/") 20 21 # Generate MD from .bzl 22 stardoc( 23 name = out_file.replace("/", "_").replace(".md", "-docgen"), 24 out = out_file.replace(".md", "-docgen.md"), 25 input = bzl_library_target + ".bzl", 26 rule_template = rule_template, 27 deps = [bzl_library_target], 28 ) 29 30 # Ensure that the generated MD has been updated in the local source tree 31 diff_test( 32 name = out_file.replace("/", "_").replace(".md", "-difftest"), 33 failure_message = "Please run \"bazel run //docs:update\"", 34 # Source file 35 file1 = out_label, 36 # Output from stardoc rule above 37 file2 = out_file.replace(".md", "-docgen.md"), 38 ) 39 40def update_docs( 41 name = "update", 42 docs_folder = "docs"): 43 """Creates a sh_binary target which copies over generated doc files to the local source tree. 44 45 This is to be used in tandem with `stardoc_with_diff_test()` to produce a convenient workflow 46 for generating, testing, and updating all doc files as follows: 47 48 ``` bash 49 bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update 50 ``` 51 52 eg. 53 54 ``` bash 55 bazel build //docs/... && bazel test //docs/... && bazel run //docs:update 56 ``` 57 58 Args: 59 name: the name of the sh_binary target 60 docs_folder: the name of the folder containing the doc files in the local source tree 61 """ 62 content = ["#!/usr/bin/env bash", "cd ${BUILD_WORKSPACE_DIRECTORY}"] 63 data = [] 64 for r in native.existing_rules().values(): 65 if r["kind"] == "stardoc": 66 doc_gen = r["out"] 67 if doc_gen.startswith(":"): 68 doc_gen = doc_gen[1:] 69 doc_dest = doc_gen.replace("-docgen.md", ".md") 70 data.append(doc_gen) 71 content.append("cp -fv bazel-bin/{0}/{1} {2}".format(docs_folder, doc_gen, doc_dest)) 72 73 update_script = name + ".sh" 74 write_file( 75 name = "gen_" + name, 76 out = update_script, 77 content = content, 78 ) 79 80 native.sh_binary( 81 name = name, 82 srcs = [update_script], 83 data = data, 84 ) 85