docgen/docgen.bzl

# 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
    )