1# Copyright 2023 The Bazel Authors. All rights reserved. 2# 3# Licensed under the Apache License, Version 2.0 (the "License"); 4# you may not use this file except in compliance with the License. 5# You may obtain a copy of the License at 6# 7# http://www.apache.org/licenses/LICENSE-2.0 8# 9# Unless required by applicable law or agreed to in writing, software 10# distributed under the License is distributed on an "AS IS" BASIS, 11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12# See the License for the specific language governing permissions and 13# limitations under the License. 14 15load("@bazel_skylib//:bzl_library.bzl", "bzl_library") 16load("@dev_pip//:requirements.bzl", "requirement") 17load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED") # buildifier: disable=bzl-visibility 18load("//python/private:util.bzl", "IS_BAZEL_7_OR_HIGHER") # buildifier: disable=bzl-visibility 19load("//python/uv/private:lock.bzl", "lock") # buildifier: disable=bzl-visibility 20load("//sphinxdocs:readthedocs.bzl", "readthedocs_install") 21load("//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs") 22load("//sphinxdocs:sphinx_docs_library.bzl", "sphinx_docs_library") 23load("//sphinxdocs:sphinx_stardoc.bzl", "sphinx_stardoc", "sphinx_stardocs") 24 25package(default_visibility = ["//:__subpackages__"]) 26 27licenses(["notice"]) # Apache 2.0 28 29# We only build for Linux and Mac because: 30# 1. The actual doc process only runs on Linux 31# 2. Mac is a common development platform, and is close enough to Linux 32# it's feasible to make work. 33# Making CI happy under Windows is too much of a headache, though, so we don't 34# bother with that. 35_TARGET_COMPATIBLE_WITH = select({ 36 "@platforms//os:linux": [], 37 "@platforms//os:macos": [], 38 "//conditions:default": ["@platforms//:incompatible"], 39}) if BZLMOD_ENABLED else ["@platforms//:incompatible"] 40 41# See README.md for instructions. Short version: 42# * `bazel run //docs:docs.serve` in a separate terminal 43# * `ibazel build //docs:docs` to automatically rebuild docs 44sphinx_docs( 45 name = "docs", 46 srcs = glob( 47 include = [ 48 "*.md", 49 "**/*.md", 50 "_static/**", 51 "_includes/**", 52 ], 53 exclude = [ 54 "README.md", 55 "_*", 56 "*.inv*", 57 ], 58 ), 59 config = "conf.py", 60 formats = [ 61 "html", 62 ], 63 renamed_srcs = { 64 "//:CHANGELOG.md": "changelog.md", 65 "//:CONTRIBUTING.md": "contributing.md", 66 "//sphinxdocs/inventories:bazel_inventory": "bazel_inventory.inv", 67 }, 68 sphinx = ":sphinx-build", 69 strip_prefix = package_name() + "/", 70 tags = ["docs"], 71 target_compatible_with = _TARGET_COMPATIBLE_WITH, 72 deps = [ 73 ":bzl_api_docs", 74 ":py_api_srcs", 75 ":py_runtime_pair", 76 "//sphinxdocs/docs:docs_lib", 77 ], 78) 79 80sphinx_stardocs( 81 name = "bzl_api_docs", 82 srcs = [ 83 "//python:defs_bzl", 84 "//python:packaging_bzl", 85 "//python:pip_bzl", 86 "//python:py_binary_bzl", 87 "//python:py_cc_link_params_info_bzl", 88 "//python:py_exec_tools_info_bzl", 89 "//python:py_exec_tools_toolchain_bzl", 90 "//python:py_executable_info_bzl", 91 "//python:py_library_bzl", 92 "//python:py_runtime_bzl", 93 "//python:py_runtime_info_bzl", 94 "//python:py_test_bzl", 95 "//python:repositories_bzl", 96 "//python/api:api_bzl", 97 "//python/cc:py_cc_toolchain_bzl", 98 "//python/cc:py_cc_toolchain_info_bzl", 99 "//python/entry_points:py_console_script_binary_bzl", 100 "//python/private:py_binary_rule_bzl", 101 "//python/private:py_cc_toolchain_rule_bzl", 102 "//python/private:py_library_rule_bzl", 103 "//python/private:py_runtime_rule_bzl", 104 "//python/private:py_test_rule_bzl", 105 "//python/private/api:py_common_api_bzl", 106 ] + ([ 107 # Bazel 6 + Stardoc isn't able to parse something about the python bzlmod extension 108 "//python/extensions:python_bzl", 109 ] if IS_BAZEL_7_OR_HIGHER else []) + ([ 110 # This depends on @pythons_hub, which is only created under bzlmod, 111 "//python/extensions:pip_bzl", 112 ] if IS_BAZEL_7_OR_HIGHER and BZLMOD_ENABLED else []), 113 prefix = "api/rules_python/", 114 tags = ["docs"], 115 target_compatible_with = _TARGET_COMPATIBLE_WITH, 116) 117 118sphinx_stardoc( 119 name = "py_runtime_pair", 120 src = "//python/private:py_runtime_pair_rule_bzl", 121 prefix = "api/rules_python/", 122 tags = ["docs"], 123 target_compatible_with = _TARGET_COMPATIBLE_WITH, 124) 125 126sphinx_docs_library( 127 name = "py_api_srcs", 128 srcs = [ 129 "//python/runfiles", 130 ], 131 strip_prefix = "python/", 132) 133 134readthedocs_install( 135 name = "readthedocs_install", 136 docs = [":docs"], 137 target_compatible_with = _TARGET_COMPATIBLE_WITH, 138) 139 140sphinx_build_binary( 141 name = "sphinx-build", 142 target_compatible_with = _TARGET_COMPATIBLE_WITH, 143 deps = [ 144 requirement("sphinx"), 145 requirement("sphinx_rtd_theme"), 146 requirement("myst_parser"), 147 requirement("readthedocs_sphinx_ext"), 148 requirement("typing_extensions"), 149 requirement("sphinx_autodoc2"), 150 requirement("sphinx_reredirects"), 151 "//sphinxdocs/src/sphinx_bzl", 152 ], 153) 154 155# Run bazel run //docs:requirements.update 156lock( 157 name = "requirements", 158 srcs = ["pyproject.toml"], 159 out = "requirements.txt", 160 upgrade = True, 161 visibility = ["//private:__pkg__"], 162) 163 164# Temporary compatibility aliases for some other projects depending on the old 165# bzl_library targets. 166alias( 167 name = "defs", 168 actual = "//python:defs_bzl", 169 deprecation = "Use //python:defs_bzl instead; targets under //docs are internal.", 170 visibility = ["//visibility:public"], 171) 172 173alias( 174 name = "bazel_repo_tools", 175 actual = "//python/private:bazel_tools_bzl", 176 deprecation = "Use @bazel_tools//tools:bzl_srcs instead; targets under //docs are internal.", 177 visibility = ["//visibility:public"], 178) 179 180bzl_library( 181 name = "pip_install_bzl", 182 deprecation = "Use //python:pip_bzl or //python/pip_install:pip_repository_bzl instead; " + 183 "targets under //docs are internal.", 184 visibility = ["//visibility:public"], 185 deps = [ 186 "//python:pip_bzl", 187 "//python/pip_install:pip_repository_bzl", 188 ], 189) 190 191alias( 192 name = "requirements_parser_bzl", 193 actual = "//python/pip_install:pip_repository_bzl", 194 deprecation = "Use //python/pip_install:pip_repository_bzl instead; Both the requirements " + 195 "parser and targets under //docs are internal", 196 visibility = ["//visibility:public"], 197) 198