1*d6050574SRomain Jobredeaux# Copyright 2023 The Bazel Authors. All rights reserved. 2*d6050574SRomain Jobredeaux# 3*d6050574SRomain Jobredeaux# Licensed under the Apache License, Version 2.0 (the "License"); 4*d6050574SRomain Jobredeaux# you may not use this file except in compliance with the License. 5*d6050574SRomain Jobredeaux# You may obtain a copy of the License at 6*d6050574SRomain Jobredeaux# 7*d6050574SRomain Jobredeaux# http://www.apache.org/licenses/LICENSE-2.0 8*d6050574SRomain Jobredeaux# 9*d6050574SRomain Jobredeaux# Unless required by applicable law or agreed to in writing, software 10*d6050574SRomain Jobredeaux# distributed under the License is distributed on an "AS IS" BASIS, 11*d6050574SRomain Jobredeaux# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12*d6050574SRomain Jobredeaux# See the License for the specific language governing permissions and 13*d6050574SRomain Jobredeaux# limitations under the License. 14*d6050574SRomain Jobredeaux 15*d6050574SRomain Jobredeaux"""Rules to help generate rules_testing docs.""" 16*d6050574SRomain Jobredeaux 17*d6050574SRomain Jobredeauxload("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc") 18*d6050574SRomain Jobredeauxload("@bazel_skylib//rules:build_test.bzl", "build_test") 19*d6050574SRomain Jobredeaux 20*d6050574SRomain Jobredeauxdef sphinx_stardocs(name, bzl_libraries, **kwargs): 21*d6050574SRomain Jobredeaux """Generate Sphinx-friendly markdown docs using Stardoc for bzl libraries. 22*d6050574SRomain Jobredeaux 23*d6050574SRomain Jobredeaux Args: 24*d6050574SRomain Jobredeaux name: str, the name of the resulting file group with the generated docs. 25*d6050574SRomain Jobredeaux bzl_libraries: list of targets, the libraries to generate docs for. 26*d6050574SRomain Jobredeaux The must be in "//foo:{name}_bzl" format; the `{name}` portion 27*d6050574SRomain Jobredeaux will become the output file name. 28*d6050574SRomain Jobredeaux **kwargs: Additional kwargs to pass onto generated targets (e.g. 29*d6050574SRomain Jobredeaux tags) 30*d6050574SRomain Jobredeaux """ 31*d6050574SRomain Jobredeaux 32*d6050574SRomain Jobredeaux docs = [] 33*d6050574SRomain Jobredeaux for label in bzl_libraries: 34*d6050574SRomain Jobredeaux lib_name = Label(label).name.replace("_bzl", "") 35*d6050574SRomain Jobredeaux 36*d6050574SRomain Jobredeaux doc_rule_name = "_{}_{}".format(name, lib_name) 37*d6050574SRomain Jobredeaux sphinx_stardoc( 38*d6050574SRomain Jobredeaux name = "_{}_{}".format(name, lib_name), 39*d6050574SRomain Jobredeaux out = lib_name + ".md", 40*d6050574SRomain Jobredeaux input = label.replace("_bzl", ".bzl"), 41*d6050574SRomain Jobredeaux deps = [label], 42*d6050574SRomain Jobredeaux **kwargs 43*d6050574SRomain Jobredeaux ) 44*d6050574SRomain Jobredeaux docs.append(doc_rule_name) 45*d6050574SRomain Jobredeaux 46*d6050574SRomain Jobredeaux native.filegroup( 47*d6050574SRomain Jobredeaux name = name, 48*d6050574SRomain Jobredeaux srcs = docs, 49*d6050574SRomain Jobredeaux **kwargs 50*d6050574SRomain Jobredeaux ) 51*d6050574SRomain Jobredeaux build_test( 52*d6050574SRomain Jobredeaux name = name + "_build_test", 53*d6050574SRomain Jobredeaux targets = docs, 54*d6050574SRomain Jobredeaux **kwargs 55*d6050574SRomain Jobredeaux ) 56*d6050574SRomain Jobredeaux 57*d6050574SRomain Jobredeauxdef sphinx_stardoc(**kwargs): 58*d6050574SRomain Jobredeaux stardoc( 59*d6050574SRomain Jobredeaux # copybara-marker: stardoc format 60*d6050574SRomain Jobredeaux func_template = "func_template.vm", 61*d6050574SRomain Jobredeaux header_template = "header_template.vm", 62*d6050574SRomain Jobredeaux rule_template = "rule_template.vm", 63*d6050574SRomain Jobredeaux provider_template = "provider_template.vm", 64*d6050574SRomain Jobredeaux **kwargs 65*d6050574SRomain Jobredeaux ) 66