1# Copyright 2023 The Bazel Authors. All rights reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14
15load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
16load("@bazel_skylib//rules:write_file.bzl", "write_file")
17load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
18
19def stardoc_with_diff_test(
20 bzl_library_target,
21 out_label,
22 rule_template = "@io_bazel_stardoc//stardoc:templates/markdown_tables/rule.vm"):
23 """Creates a stardoc target coupled with a diff_test for a given bzl_library.
24
25 This is helpful for minimizing boilerplate when lots of stardoc targets are to be generated.
26
27 Args:
28 bzl_library_target: the label of the bzl_library target to generate documentation for
29 out_label: the label of the output MD file
30 rule_template: the label or path to the Velocity rule template to use with stardoc
31 """
32
33 out_file = out_label.replace("//", "").replace(":", "/")
34
35 # Generate MD from .bzl
36 stardoc(
37 name = out_file.replace("/", "_").replace(".md", "-docgen"),
38 out = out_file.replace(".md", "-docgen.md"),
39 input = bzl_library_target + ".bzl",
40 rule_template = rule_template,
41 deps = [bzl_library_target],
42 )
43
44 # Ensure that the generated MD has been updated in the local source tree
45 diff_test(
46 name = out_file.replace("/", "_").replace(".md", "-difftest"),
47 failure_message = "Please run \"bazel run //docs:update\"",
48 # Source file
49 file1 = out_label,
50 # Output from stardoc rule above
51 file2 = out_file.replace(".md", "-docgen.md"),
52 )
53
54def update_docs(
55 name = "update",
56 docs_folder = "docs"):
57 """Creates a sh_binary target which copies over generated doc files to the local source tree.
58
59 This is to be used in tandem with `stardoc_with_diff_test()` to produce a convenient workflow
60 for generating, testing, and updating all doc files as follows:
61
62 ``` bash
63 bazel build //{docs_folder}/... && bazel test //{docs_folder}/... && bazel run //{docs_folder}:update
64 ```
65
66 eg.
67
68 ``` bash
69 bazel build //docs/... && bazel test //docs/... && bazel run //docs:update
70 ```
71
72 Args:
73 name: the name of the sh_binary target
74 docs_folder: the name of the folder containing the doc files in the local source tree
75 """
76 content = ["#!/usr/bin/env bash", "cd ${BUILD_WORKSPACE_DIRECTORY}"]
77 data = []
78 for r in native.existing_rules().values():
79 if r["kind"] == "stardoc":
80 doc_gen = r["out"]
81 if doc_gen.startswith(":"):
82 doc_gen = doc_gen[1:]
83 doc_dest = doc_gen.replace("-docgen.md", ".md")
84 data.append(doc_gen)
85 content.append("cp -fv bazel-bin/{0}/{1} {2}".format(docs_folder, doc_gen, doc_dest))
86
87 update_script = name + ".sh"
88 write_file(
89 name = "gen_" + name,
90 out = update_script,
91 content = content,
92 )
93
94 native.sh_binary(
95 name = name,
96 srcs = [update_script],
97 data = data,
98 )
View as plain text