1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
# 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("@dev_pip//:requirements.bzl", "requirement")
load("//python:pip.bzl", "compile_pip_requirements")
load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED") # buildifier: disable=bzl-visibility
load("//python/private:util.bzl", "IS_BAZEL_7_OR_HIGHER") # buildifier: disable=bzl-visibility
load("//sphinxdocs:readthedocs.bzl", "readthedocs_install")
load("//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs", "sphinx_inventory")
load("//sphinxdocs:sphinx_stardoc.bzl", "sphinx_stardocs")
# 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"],
})
# See README.md for instructions. Short version:
# * `bazel run //docs/sphinx:docs.serve` in a separate terminal
# * `ibazel build //docs/sphinx:docs` to automatically rebuild docs
sphinx_docs(
name = "docs",
srcs = [
":bazel_inventory",
":bzl_api_docs",
] + glob(
include = [
"*.md",
"**/*.md",
"_static/**",
"_includes/**",
],
exclude = [
"README.md",
"_*",
"*.inv*",
],
),
config = "conf.py",
formats = [
"html",
],
renamed_srcs = {
"//:CHANGELOG.md": "changelog.md",
"//:CONTRIBUTING.md": "contributing.md",
},
sphinx = ":sphinx-build",
strip_prefix = package_name() + "/",
tags = ["docs"],
target_compatible_with = _TARGET_COMPATIBLE_WITH,
)
sphinx_inventory(
name = "bazel_inventory",
src = "bazel_inventory.txt",
)
sphinx_stardocs(
name = "bzl_api_docs",
docs = {
"api/cc/py_cc_toolchain.md": dict(
dep = "//python/private:py_cc_toolchain_bzl",
input = "//python/private:py_cc_toolchain_rule.bzl",
public_load_path = "//python/cc:py_cc_toolchain.bzl",
),
"api/cc/py_cc_toolchain_info.md": "//python/cc:py_cc_toolchain_info_bzl",
"api/defs.md": "//python:defs_bzl",
"api/entry_points/py_console_script_binary.md": "//python/entry_points:py_console_script_binary_bzl",
"api/packaging.md": "//python:packaging_bzl",
"api/pip.md": "//python:pip_bzl",
} | ({
# Bazel 6 + Stardoc isn't able to parse something about the python bzlmod extension
"api/extensions/python.md": "//python/extensions:python_bzl",
} if IS_BAZEL_7_OR_HIGHER else {}) | ({
# This depends on @pythons_hub, which is only created under bzlmod,
"api/extensions/pip.md": "//python/extensions:pip_bzl",
} if IS_BAZEL_7_OR_HIGHER and BZLMOD_ENABLED else {}),
footer = "_stardoc_footer.md",
tags = ["docs"],
target_compatible_with = _TARGET_COMPATIBLE_WITH,
)
readthedocs_install(
name = "readthedocs_install",
docs = [":docs"],
target_compatible_with = _TARGET_COMPATIBLE_WITH,
)
sphinx_build_binary(
name = "sphinx-build",
target_compatible_with = _TARGET_COMPATIBLE_WITH,
deps = [
requirement("sphinx"),
requirement("sphinx_rtd_theme"),
requirement("myst_parser"),
requirement("readthedocs_sphinx_ext"),
],
)
# Run bazel run //docs/sphinx:requirements.update
compile_pip_requirements(
name = "requirements",
src = "pyproject.toml",
requirements_txt = "requirements.txt",
target_compatible_with = _TARGET_COMPATIBLE_WITH,
)
|
