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

package(default_visibility = ["//visibility:public"])

licenses(["notice"])  # Apache 2.0

_DOCS = {
    "packaging": "//docs:packaging-docs",
    "pip": "//docs:pip-docs",
    "pip_repository": "//docs:pip-repository",
    "py_cc_toolchain": "//docs:py_cc_toolchain-docs",
    "py_cc_toolchain_info": "//docs:py_cc_toolchain_info-docs",
    "py_console_script_binary": "//docs:py-console-script-binary",
    "python": "//docs:core-docs",
}

# We define these bzl_library targets here rather than in the //python package
# because they're only used for doc generation. This way, we avoid requiring
# our users to depend on Skylib.

bzl_library(
    name = "bazel_repo_tools",
    srcs = [
        "@bazel_tools//tools:bzl_srcs",
    ],
)

bzl_library(
    name = "defs",
    srcs = [
        "//python:defs.bzl",
        "//python/private:reexports.bzl",
    ],
    deps = [
        ":bazel_repo_tools",
        "//python:defs_bzl",
        "//python/private:reexports_bzl",
    ],
)

bzl_library(
    name = "pip_install_bzl",
    srcs = [
        "//python:bzl",
        "//python/pip_install:bzl",
    ],
    deps = [
        ":defs",
        "//:version.bzl",
    ],
)

bzl_library(
    name = "requirements_parser_bzl",
    srcs = [
        "//python/pip_install:requirements_parser.bzl",
    ],
)

bzl_library(
    name = "packaging_bzl",
    srcs = [
        "//python:packaging.bzl",
        "//python/private:py_package.bzl",
        "//python/private:py_wheel.bzl",
        "//python/private:stamp.bzl",
        "//python/private:util.bzl",
    ],
    deps = [
        "//python/private:util_bzl",
    ],
)

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

stardoc(
    name = "core-docs",
    out = "python.md_",
    input = "//python:defs.bzl",
    target_compatible_with = _NOT_WINDOWS,
    deps = [":defs"],
)

stardoc(
    name = "pip-docs",
    out = "pip.md_",
    input = "//python:pip.bzl",
    target_compatible_with = _NOT_WINDOWS,
    deps = [
        ":bazel_repo_tools",
        ":pip_install_bzl",
        "@bazel_skylib//lib:versions",
    ],
)

stardoc(
    name = "pip-repository",
    out = "pip_repository.md_",
    input = "//python/pip_install:pip_repository.bzl",
    target_compatible_with = _NOT_WINDOWS,
    deps = [
        ":bazel_repo_tools",
        ":pip_install_bzl",
        ":requirements_parser_bzl",
        "@bazel_skylib//lib:versions",
    ],
)

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

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

stardoc(
    name = "py_cc_toolchain-docs",
    out = "py_cc_toolchain.md_",
    # 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 = _NOT_WINDOWS,
    deps = ["//python/private:py_cc_toolchain_bzl"],
)

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

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

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.keys()
    ],
    target_compatible_with = _NOT_WINDOWS,
)

sh_binary(
    name = "update",
    srcs = ["update.sh"],
    data = _DOCS.values(),
    target_compatible_with = _NOT_WINDOWS,
)