docs/BUILD.bazel

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

load("@bazel_skylib//rules:build_test.bzl", "build_test")
load("@sphinxdocs//sphinxdocs:readthedocs.bzl", "readthedocs_install")
load("@sphinxdocs//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
load("@sphinxdocs//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library")
load("@sphinxdocs//sphinxdocs:sphinx_stardoc.bzl", "sphinx_stardoc", "sphinx_stardocs")
load("//python:defs.bzl", "py_binary")
load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED")  # buildifier: disable=bzl-visibility
load("//python/private:common_labels.bzl", "labels")  # buildifier: disable=bzl-visibility

package(default_visibility = ["//:__subpackages__"])

licenses(["notice"])  # Apache 2.0

# We only build for Linux and Mac because:
# 1. The actual doc process only runs on Linux
# 2. Mac is a common development platform, and is close enough to Linux
#    it's feasible to make work.
# Making CI happy under Windows is too much of a headache, though, so we don't
# bother with that.
_TARGET_COMPATIBLE_WITH = select({
    "@platforms//os:linux": [],
    "@platforms//os:macos": [],
    "//conditions:default": ["@platforms//:incompatible"],
}) if BZLMOD_ENABLED else ["@platforms//:incompatible"]

py_binary(
    name = "merge_changelog",
    srcs = ["merge_changelog.py"],
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
    deps = [
        "//dev/release:changelog_news",
    ],
)

genrule(
    name = "merged_changelog",
    srcs = [
        "//:CHANGELOG.md",
        "//news:news_files",
    ],
    outs = ["changelog.md"],
    cmd = "$(location :merge_changelog) --changelog $(location //:CHANGELOG.md) --news-dir news --output $@",
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
    tools = [":merge_changelog"],
)

# See README.md for instructions. Short version:
# * `bazel run //docs:docs.serve` in a separate terminal
# * `ibazel build //docs:docs` to automatically rebuild docs
sphinx_docs(
    name = "docs",
    srcs = glob(
        include = [
            "*.md",
            "**/*.md",
            "_static/**",
            "_includes/**",
        ],
        exclude = [
            "README.md",
            "_*",
            "*.inv*",
        ],
    ) + ["//gazelle/docs"],
    config = "conf.py",
    formats = [
        "html",
    ],
    renamed_srcs = {
        "//:CONTRIBUTING.md": "contributing.md",
        ":merged_changelog": "changelog.md",
        "@sphinxdocs//sphinxdocs/inventories:bazel_inventory": "bazel_inventory.inv",
    },
    sphinx = ":sphinx-build",
    strip_prefix = package_name() + "/",
    tags = ["docs"],
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
    deps = [
        ":bzl_api_docs",
        ":py_api_srcs",
        ":py_runtime_pair",
        "@sphinxdocs//docs:docs_lib",
    ],
)

build_test(
    name = "docs_build_test",
    targets = [":docs"],
)

sphinx_stardocs(
    name = "bzl_api_docs",
    srcs = [
        "//python:defs",
        "//python:features",
        "//python:packaging",
        "//python:pip",
        "//python:proto",
        "//python:py_binary",
        "//python:py_cc_link_params_info",
        "//python:py_exec_tools_info",
        "//python:py_exec_tools_toolchain",
        "//python:py_executable_info",
        "//python:py_info",
        "//python:py_library",
        "//python:py_runtime",
        "//python:py_runtime_info",
        "//python:py_test",
        "//python:repositories",
        "//python/api",
        "//python/api:attr_builders",
        "//python/api:executables",
        "//python/api:libraries",
        "//python/api:rule_builders",
        "//python/cc:py_cc_toolchain",
        "//python/cc:py_cc_toolchain_info",
        "//python/cc:py_extension",
        "//python/entry_points:py_console_script_binary",
        "//python/extensions:config",
        "//python/extensions:python",
        "//python/local_toolchains:repos",
        "//python/private:attr_builders",
        "//python/private:builders",
        "//python/private:builders_util",
        "//python/private:py_binary_rule",
        "//python/private:py_cc_toolchain_rule",
        "//python/private:py_info",
        "//python/private:py_library_rule",
        "//python/private:py_runtime_rule",
        "//python/private:py_test_rule",
        "//python/private:rule_builders",
        "//python/private/api:py_common_api",
        "//python/private/pypi:config_settings",
        "//python/private/pypi:env_marker_info",
        "//python/private/pypi:pip_archive",
        "//python/private/pypi:pkg_aliases",
        "//python/private/pypi:whl_archive",
        "//python/private/pypi:whl_config_setting",
        "//python/private/pypi:whl_library",
        "//python/private/zipapp:py_zipapp_rule",
        "//python/uv",
        "//python/uv:lock",
        "//python/uv:uv_toolchain",
        "//python/uv:uv_toolchain_info",
        "//python/zipapp:py_zipapp_binary",
        "//python/zipapp:py_zipapp_test",
    ] + ([
        # This depends on @pythons_hub, which is only created under bzlmod,
        "//python/extensions:pip",
    ] if BZLMOD_ENABLED else []),
    prefix = "api/rules_python/",
    tags = ["docs"],
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
)

sphinx_stardoc(
    name = "py_runtime_pair",
    src = "//python/private:py_runtime_pair_rule",
    prefix = "api/rules_python/",
    tags = ["docs"],
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
)

sphinx_docs_library(
    name = "py_api_srcs",
    srcs = [
        "//python/runfiles",
    ],
    strip_prefix = "python/",
)

readthedocs_install(
    name = "readthedocs_install",
    docs = [":docs"],
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
)

sphinx_build_binary(
    name = "sphinx-build",
    config_settings = {
        labels.BOOTSTRAP_IMPL: "script",
        labels.VENVS_SITE_PACKAGES: "yes",
        labels.PY_FREETHREADED: "yes",
        labels.PYTHON_VERSION: "3.14",
    },
    target_compatible_with = _TARGET_COMPATIBLE_WITH,
    deps = [
        "@dev_pip//myst_parser",
        "@dev_pip//pytest",
        "@dev_pip//readthedocs_sphinx_ext",
        "@dev_pip//sphinx",
        "@dev_pip//sphinx_autodoc2",
        "@dev_pip//sphinx_reredirects",
        "@dev_pip//sphinx_rtd_theme",
        "@dev_pip//typing_extensions",
        "@sphinxdocs//sphinxdocs/src/sphinx_bzl",
    ],
)