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 15"""Rules to help generate rules_testing docs.""" 16 17load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") 18load("@bazel_skylib//rules:build_test.bzl", "build_test") 19 20def sphinx_stardocs(name, bzl_libraries, **kwargs): 21 """Generate Sphinx-friendly markdown docs using Stardoc for bzl libraries. 22 23 Args: 24 name: str, the name of the resulting file group with the generated docs. 25 bzl_libraries: list of targets, the libraries to generate docs for. 26 The must be in "//foo:{name}_bzl" format; the `{name}` portion 27 will become the output file name. 28 **kwargs: Additional kwargs to pass onto generated targets (e.g. 29 tags) 30 """ 31 32 docs = [] 33 for label in bzl_libraries: 34 lib_name = Label(label).name.replace("_bzl", "") 35 36 doc_rule_name = "_{}_{}".format(name, lib_name) 37 sphinx_stardoc( 38 name = "_{}_{}".format(name, lib_name), 39 out = lib_name + ".md", 40 input = label.replace("_bzl", ".bzl"), 41 deps = [label], 42 **kwargs 43 ) 44 docs.append(doc_rule_name) 45 46 native.filegroup( 47 name = name, 48 srcs = docs, 49 **kwargs 50 ) 51 build_test( 52 name = name + "_build_test", 53 targets = docs, 54 **kwargs 55 ) 56 57def sphinx_stardoc(**kwargs): 58 stardoc( 59 # copybara-marker: stardoc format 60 func_template = "func_template.vm", 61 header_template = "header_template.vm", 62 rule_template = "rule_template.vm", 63 provider_template = "provider_template.vm", 64 **kwargs 65 ) 66