docs/BUILD.bazel

# Copyright 2017 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.

load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
load("@bazel_skylib//rules:diff_test.bzl", "diff_test")
load("@bazel_skylib//rules:write_file.bzl", "write_file")
load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")

# NOTE: Only public visibility for historical reasons.
# This package is only for rules_python to generate its own docs.
package(default_visibility = ["//visibility:public"])

licenses(["notice"])  # Apache 2.0

_DOCS = [
    "packaging",
    "pip",
    "py_cc_toolchain",
    "py_cc_toolchain_info",
    # TODO @aignas 2023-10-09: move some of the example code from the `.bzl` files
    # to the markdown once #1476 is merged.
    "py_console_script_binary",
    "python",
]

# Temporary compatibility aliases for some other projects depending on the old
# bzl_library targets.
alias(
    name = "defs",
    actual = "//python:defs_bzl",
    deprecation = "Use //python:defs_bzl instead; targets under //docs are internal.",
)

alias(
    name = "bazel_repo_tools",
    actual = "//python/private:bazel_tools_bzl",
    deprecation = "Use @bazel_tools//tools:bzl_srcs instead; targets under //docs are internal.",
)

bzl_library(
    name = "pip_install_bzl",
    deprecation = "Use //python:pip_bzl or //python/pip_install:pip_repository_bzl instead; " +
                  "targets under //docs are internal.",
    deps = [
        "//python:pip_bzl",
        "//python/pip_install:pip_repository_bzl",
    ],
)

alias(
    name = "requirements_parser_bzl",
    actual = "//python/pip_install:pip_repository_bzl",
    deprecation = "Use //python/pip_install:pip_repository_bzl instead; Both the requirements " +
                  "parser and targets under //docs are internal",
)

# TODO: Stardoc does not guarantee consistent outputs accross platforms (Unix/Windows).
# As a result we do not build or test docs on Windows.
_TARGET_COMPATIBLE_WITH = select({
    "@platforms//os:linux": [],
    "@platforms//os:macos": [],
    "//conditions:default": ["@platforms//:incompatible"],
})

stardoc(
    name = "core-docs",
    out = "python.md.gen",
    input = "//python:defs.bzl",
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
    deps = [
        "//python:defs_bzl",
    ],
)

stardoc(
    name = "pip-docs",
    out = "pip.md.gen",
    input = "//python:pip.bzl",
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
    deps = [
        "//python:pip_bzl",
    ],
)

stardoc(
    name = "py-console-script-binary",
    out = "py_console_script_binary.md.gen",
    input = "//python/entry_points:py_console_script_binary.bzl",
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
    deps = [
        "//python/entry_points:py_console_script_binary_bzl",
    ],
)

stardoc(
    name = "packaging-docs",
    out = "packaging.md.gen",
    input = "//python:packaging.bzl",
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
    deps = ["//python:packaging_bzl"],
)

stardoc(
    name = "py_cc_toolchain-docs",
    out = "py_cc_toolchain.md.gen",
    # NOTE: The public file isn't used as the input because it would document
    # the macro, which doesn't have the attribute documentation. The macro
    # doesn't do anything interesting to users, so bypass it to avoid having to
    # copy/paste all the rule's doc in the macro.
    input = "//python/private:py_cc_toolchain_rule.bzl",
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
    deps = ["//python/private:py_cc_toolchain_bzl"],
)

stardoc(
    name = "py_cc_toolchain_info-docs",
    out = "py_cc_toolchain_info.md.gen",
    input = "//python/cc:py_cc_toolchain_info.bzl",
    deps = ["//python/cc:py_cc_toolchain_info_bzl"],
)

[
    # retain any modifications made by the maintainers above the generated part
    genrule(
        name = "merge_" + k,
        srcs = [
            k + ".md",
            k + ".md.gen",
        ],
        outs = [k + ".md_"],
        cmd = ";".join([
            "sed -En '/{comment_bait}/q;p' <$(location {first}) > $@",
            "sed -E 's/{comment_doc}/{comment_note}/g' $(location {second}) >> $@",
        ]).format(
            comment_bait = "Stardoc: http:..skydoc.bazel.build -->",
            comment_doc = "^<!.*(Stardoc:.*skydoc.bazel.build.*)",
            comment_note = "<!-- Everything including and below this line replaced " +
                           "with output from \\1",
            first = k + ".md",
            second = k + ".md.gen",
        ),
    )
    for k in _DOCS
]

[
    diff_test(
        name = "check_" + k,
        failure_message = "Please run:   bazel run //docs:update",
        file1 = k + ".md",
        file2 = k + ".md_",
        tags = ["doc_check_test"],
        target_compatible_with = _TARGET_COMPATIBLE_WITH,
    )
    for k in _DOCS
]

write_file(
    name = "gen_update",
    out = "update.sh",
    content = [
        "#!/usr/bin/env bash",
        "cd $BUILD_WORKSPACE_DIRECTORY",
    ] + [
        "cp -fv bazel-bin/docs/{0}.md_ docs/{0}.md".format(k)
        for k in _DOCS
    ],
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
)

sh_binary(
    name = "update",
    srcs = ["update.sh"],
    data = ["merge_" + k for k in _DOCS],
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
)