1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
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,
)
|
