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
|
# Copyright 2023 The Bazel Authors. All rights reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Rules to help generate rules_testing docs."""
load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
load("@bazel_skylib//rules:build_test.bzl", "build_test")
def sphinx_stardocs(name, bzl_libraries, **kwargs):
"""Generate Sphinx-friendly markdown docs using Stardoc for bzl libraries.
Args:
name: str, the name of the resulting file group with the generated docs.
bzl_libraries: list of targets, the libraries to generate docs for.
The must be in "//foo:{name}_bzl" format; the `{name}` portion
will become the output file name.
**kwargs: Additional kwargs to pass onto generated targets (e.g.
tags)
"""
# Stardoc doesn't yet work with bzlmod; we can detect this by
# looking for "@@" vs "@" in labels.
if "@@" in str(Label("//:X")):
kwargs["target_compatible_with"] = ["@platforms//:incompatible"]
docs = []
for label in bzl_libraries:
lib_name = Label(label).name.replace("_bzl", "")
doc_rule_name = "_{}_{}".format(name, lib_name)
sphinx_stardoc(
name = "_{}_{}".format(name, lib_name),
out = lib_name + ".md",
input = label.replace("_bzl", ".bzl"),
deps = [label],
**kwargs
)
docs.append(doc_rule_name)
native.filegroup(
name = name,
srcs = docs,
**kwargs
)
build_test(
name = name + "_build_test",
targets = docs,
**kwargs
)
def sphinx_stardoc(**kwargs):
stardoc(
# copybara-marker: stardoc format
func_template = "func_template.vm",
header_template = "header_template.vm",
rule_template = "rule_template.vm",
provider_template = "provider_template.vm",
**kwargs
)
|
