Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit d7d2ce7

Browse filesBrowse files
rickeylevrickeylev
authored
refactor: move docs/sphinx -> docs (#2130)
The sphinx sub-dir was only temporary as the sphinx-based docgen was implemented. With that done, the files can be moved up into the regular docs directory.
1 parent 79ca4a4 commit d7d2ce7
Copy full SHA for d7d2ce7
Expand file treeCollapse file tree

31 files changed

+219
-231
lines changed

‎.github/dependabot.yml

Copy file name to clipboardExpand all lines: .github/dependabot.yml
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ updates:
1010
- package-ecosystem: "pip"
1111
directories:
1212
# Maintain dependencies for our tools
13-
- "/docs/sphinx"
13+
- "/docs"
1414
- "/tools/publish"
1515
schedule:
1616
interval: "weekly"

‎.readthedocs.yml

Copy file name to clipboardExpand all lines: .readthedocs.yml
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,4 +11,4 @@ build:
1111
- bazel version
1212
# Put the actual build behind a shell script because its easier to modify than
1313
# the yaml config.
14-
- docs/sphinx/readthedocs_build.sh
14+
- docs/readthedocs_build.sh

‎CONTRIBUTING.md

Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,7 @@ merged:
148148

149149
* **requirements lock files**: These are usually generated by a
150150
`compile_pip_requirements` update target, which is usually in the same directory.
151-
e.g. `bazel run //docs/sphinx:requirements.update`
151+
e.g. `bazel run //docs:requirements.update`
152152

153153
## Core rules
154154

‎MODULE.bazel

Copy file name to clipboardExpand all lines: MODULE.bazel
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ dev_pip = use_extension(
9393
dev_pip.parse(
9494
hub_name = "dev_pip",
9595
python_version = "3.11",
96-
requirements_lock = "//docs/sphinx:requirements.txt",
96+
requirements_lock = "//docs:requirements.txt",
9797
)
9898
dev_pip.parse(
9999
hub_name = "pypiserver",

‎WORKSPACE

Copy file name to clipboardExpand all lines: WORKSPACE
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -122,7 +122,7 @@ install_pypiserver()
122122
pip_parse(
123123
name = "dev_pip",
124124
python_interpreter_target = interpreter,
125-
requirements_lock = "//docs/sphinx:requirements.txt",
125+
requirements_lock = "//docs:requirements.txt",
126126
)
127127

128128
load("@dev_pip//:requirements.bzl", docs_install_deps = "install_deps")

‎docs/BUILD.bazel

Copy file name to clipboardExpand all lines: docs/BUILD.bazel
+198-5Lines changed: 198 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
# Copyright 2017 The Bazel Authors. All rights reserved.
1+
# Copyright 2023 The Bazel Authors. All rights reserved.
22
#
33
# Licensed under the Apache License, Version 2.0 (the "License");
44
# you may not use this file except in compliance with the License.
55
# You may obtain a copy of the License at
66
#
7-
# http://www.apache.org/licenses/LICENSE-2.0
7+
# http://www.apache.org/licenses/LICENSE-2.0
88
#
99
# Unless required by applicable law or agreed to in writing, software
1010
# distributed under the License is distributed on an "AS IS" BASIS,
@@ -13,10 +13,199 @@
1313
# limitations under the License.
1414

1515
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
16+
load("@bazel_skylib//rules:write_file.bzl", "write_file")
17+
load("@dev_pip//:requirements.bzl", "requirement")
18+
load("//python:py_binary.bzl", "py_binary")
19+
load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED") # buildifier: disable=bzl-visibility
20+
load("//python/private:util.bzl", "IS_BAZEL_7_OR_HIGHER") # buildifier: disable=bzl-visibility
21+
load("//sphinxdocs:readthedocs.bzl", "readthedocs_install")
22+
load("//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
23+
load("//sphinxdocs:sphinx_stardoc.bzl", "sphinx_stardoc", "sphinx_stardocs")
1624

17-
# NOTE: Only public visibility for historical reasons.
18-
# This package is only for rules_python to generate its own docs.
19-
package(default_visibility = ["//visibility:public"])
25+
package(default_visibility = ["//:__subpackages__"])
26+
27+
# We only build for Linux and Mac because:
28+
# 1. The actual doc process only runs on Linux
29+
# 2. Mac is a common development platform, and is close enough to Linux
30+
# it's feasible to make work.
31+
# Making CI happy under Windows is too much of a headache, though, so we don't
32+
# bother with that.
33+
_TARGET_COMPATIBLE_WITH = select({
34+
"@platforms//os:linux": [],
35+
"@platforms//os:macos": [],
36+
"//conditions:default": ["@platforms//:incompatible"],
37+
}) if IS_BAZEL_7_OR_HIGHER else ["@platforms//:incompatible"]
38+
39+
# See README.md for instructions. Short version:
40+
# * `bazel run //docs:docs.serve` in a separate terminal
41+
# * `ibazel build //docs:docs` to automatically rebuild docs
42+
sphinx_docs(
43+
name = "docs",
44+
srcs = glob(
45+
include = [
46+
"*.md",
47+
"**/*.md",
48+
"_static/**",
49+
"_includes/**",
50+
],
51+
exclude = [
52+
"README.md",
53+
"_*",
54+
"*.inv*",
55+
],
56+
),
57+
config = "conf.py",
58+
formats = [
59+
"html",
60+
],
61+
renamed_srcs = {
62+
"//:CHANGELOG.md": "changelog.md",
63+
"//:CONTRIBUTING.md": "contributing.md",
64+
"//sphinxdocs/inventories:bazel_inventory": "bazel_inventory.inv",
65+
},
66+
sphinx = ":sphinx-build",
67+
strip_prefix = package_name() + "/",
68+
tags = ["docs"],
69+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
70+
deps = [
71+
":bzl_api_docs",
72+
"//sphinxdocs/docs:docs_lib",
73+
],
74+
)
75+
76+
sphinx_stardocs(
77+
name = "bzl_api_docs",
78+
srcs = [
79+
"//python:defs_bzl",
80+
"//python:packaging_bzl",
81+
"//python:pip_bzl",
82+
"//python:py_binary_bzl",
83+
"//python:py_cc_link_params_info_bzl",
84+
"//python:py_library_bzl",
85+
"//python:py_runtime_bzl",
86+
"//python:py_runtime_info_bzl",
87+
"//python:py_test_bzl",
88+
"//python/cc:py_cc_toolchain_info_bzl",
89+
"//python/entry_points:py_console_script_binary_bzl",
90+
"//python/private/common:py_binary_rule_bazel_bzl",
91+
"//python/private/common:py_library_rule_bazel_bzl",
92+
"//python/private/common:py_runtime_rule_bzl",
93+
"//python/private/common:py_test_rule_bazel_bzl",
94+
] + ([
95+
# Bazel 6 + Stardoc isn't able to parse something about the python bzlmod extension
96+
"//python/extensions:python_bzl",
97+
] if IS_BAZEL_7_OR_HIGHER else []) + ([
98+
# This depends on @pythons_hub, which is only created under bzlmod,
99+
"//python/extensions:pip_bzl",
100+
] if IS_BAZEL_7_OR_HIGHER and BZLMOD_ENABLED else []),
101+
prefix = "api/",
102+
tags = ["docs"],
103+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
104+
)
105+
106+
sphinx_stardoc(
107+
name = "py_cc_toolchain",
108+
src = "//python/private:py_cc_toolchain_rule.bzl",
109+
prefix = "api/",
110+
public_load_path = "//python/cc:py_cc_toolchain.bzl",
111+
tags = ["docs"],
112+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
113+
deps = ["//python/cc:py_cc_toolchain_bzl"],
114+
)
115+
116+
sphinx_stardoc(
117+
name = "py_runtime_pair",
118+
src = "//python/private:py_runtime_pair_rule_bzl",
119+
public_load_path = "//python:py_runtime_pair.bzl",
120+
tags = ["docs"],
121+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
122+
)
123+
124+
readthedocs_install(
125+
name = "readthedocs_install",
126+
docs = [":docs"],
127+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
128+
)
129+
130+
sphinx_build_binary(
131+
name = "sphinx-build",
132+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
133+
deps = [
134+
requirement("sphinx"),
135+
requirement("sphinx_rtd_theme"),
136+
requirement("myst_parser"),
137+
requirement("readthedocs_sphinx_ext"),
138+
requirement("typing_extensions"),
139+
"//sphinxdocs/src/sphinx_bzl",
140+
],
141+
)
142+
143+
_REQUIREMENTS_TARGET_COMPATIBLE_WITH = select({
144+
"@platforms//os:linux": [],
145+
"@platforms//os:macos": [],
146+
"@platforms//os:windows": [],
147+
"//conditions:default": ["@platforms//:incompatible"],
148+
}) if BZLMOD_ENABLED else ["@platforms//:incompatible"]
149+
150+
# Run bazel run //docs:requirements.update
151+
genrule(
152+
name = "requirements",
153+
srcs = ["pyproject.toml"],
154+
outs = ["_requirements.txt"],
155+
cmd = "$(UV_BIN) pip compile " + " ".join([
156+
"--custom-compile-command='bazel run //docs:requirements.update'",
157+
"--generate-hashes",
158+
"--universal",
159+
"--emit-index-url",
160+
"--no-strip-extras",
161+
"--no-build",
162+
"--python=$(PYTHON3)",
163+
"$<",
164+
"--output-file=$@",
165+
# Always try upgrading
166+
"--upgrade",
167+
]),
168+
tags = [
169+
"local",
170+
"manual",
171+
"no-cache",
172+
],
173+
target_compatible_with = _REQUIREMENTS_TARGET_COMPATIBLE_WITH,
174+
toolchains = [
175+
"//python/uv:current_toolchain",
176+
"//python:current_py_toolchain",
177+
],
178+
)
179+
180+
# Write a script that can be used for updating the in-tree version of the
181+
# requirements file
182+
write_file(
183+
name = "gen_update_requirements",
184+
out = "requirements.update.py",
185+
content = [
186+
"from os import environ",
187+
"from pathlib import Path",
188+
"from sys import stderr",
189+
"",
190+
'src = Path(environ["REQUIREMENTS_FILE"])',
191+
'dst = Path(environ["BUILD_WORKSPACE_DIRECTORY"]) / "docs" / "requirements.txt"',
192+
'print(f"Writing requirements contents from {src} to {dst}", file=stderr)',
193+
"dst.write_text(src.read_text())",
194+
'print("Success!", file=stderr)',
195+
],
196+
target_compatible_with = _REQUIREMENTS_TARGET_COMPATIBLE_WITH,
197+
)
198+
199+
py_binary(
200+
name = "requirements.update",
201+
srcs = ["requirements.update.py"],
202+
data = [":requirements"],
203+
env = {
204+
"REQUIREMENTS_FILE": "$(location :requirements)",
205+
},
206+
tags = ["manual"],
207+
target_compatible_with = _REQUIREMENTS_TARGET_COMPATIBLE_WITH,
208+
)
20209

21210
licenses(["notice"]) # Apache 2.0
22211

@@ -26,18 +215,21 @@ alias(
26215
name = "defs",
27216
actual = "//python:defs_bzl",
28217
deprecation = "Use //python:defs_bzl instead; targets under //docs are internal.",
218+
visibility = ["//visibility:public"],
29219
)
30220

31221
alias(
32222
name = "bazel_repo_tools",
33223
actual = "//python/private:bazel_tools_bzl",
34224
deprecation = "Use @bazel_tools//tools:bzl_srcs instead; targets under //docs are internal.",
225+
visibility = ["//visibility:public"],
35226
)
36227

37228
bzl_library(
38229
name = "pip_install_bzl",
39230
deprecation = "Use //python:pip_bzl or //python/pip_install:pip_repository_bzl instead; " +
40231
"targets under //docs are internal.",
232+
visibility = ["//visibility:public"],
41233
deps = [
42234
"//python:pip_bzl",
43235
"//python/pip_install:pip_repository_bzl",
@@ -49,4 +241,5 @@ alias(
49241
actual = "//python/pip_install:pip_repository_bzl",
50242
deprecation = "Use //python/pip_install:pip_repository_bzl instead; Both the requirements " +
51243
"parser and targets under //docs are internal",
244+
visibility = ["//visibility:public"],
52245
)

‎docs/sphinx/README.md renamed to ‎docs/README.md

Copy file name to clipboardExpand all lines: docs/README.md
+5-5Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,8 @@ server to serve the generated HTML, and re-generating the HTML when sources
1818
change. The quick start is:
1919

2020
```
21-
bazel run //docs/sphinx:docs.serve # Run in separate terminal
22-
ibazel build //docs/sphinx:docs # Automatically rebuilds docs
21+
bazel run //docs:docs.serve # Run in separate terminal
22+
ibazel build //docs:docs # Automatically rebuilds docs
2323
```
2424

2525
This will build the docs and start a local webserver at http://localhost:8000
@@ -47,14 +47,14 @@ integrates with Sphinx functionality such as automatic cross references,
4747
creating indexes, and using concise markup to generate rich documentation.
4848

4949
MyST features and behaviors are controlled by the Sphinx configuration file,
50-
`docs/sphinx/conf.py`. For more info, see https://myst-parser.readthedocs.io.
50+
`docs/conf.py`. For more info, see https://myst-parser.readthedocs.io.
5151

5252
## Sphinx configuration
5353

5454
The Sphinx-specific configuration files and input doc files live in
55-
docs/sphinx.
55+
docs/.
5656

57-
The Sphinx configuration is `docs/sphinx/conf.py`. See
57+
The Sphinx configuration is `docs/conf.py`. See
5858
https://www.sphinx-doc.org/ for details about the configuration file.
5959

6060
## Readthedocs configuration

‎docs/sphinx/_includes/py_console_script_binary.md renamed to ‎docs/_includes/py_console_script_binary.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/_static/css/custom.css renamed to ‎docs/_static/css/custom.css

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/api/index.md renamed to ‎docs/api/index.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/api/python/cc/index.md renamed to ‎docs/api/python/cc/index.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/api/python/config_settings/index.md renamed to ‎docs/api/python/config_settings/index.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/api/python/index.md renamed to ‎docs/api/python/index.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/api/python/runtime_env_toolchains/index.md renamed to ‎docs/api/python/runtime_env_toolchains/index.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/api/tools/precompiler/index.md renamed to ‎docs/api/tools/precompiler/index.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/conf.py renamed to ‎docs/conf.py

Copy file name to clipboardExpand all lines: docs/conf.py
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
# for more settings
1717

1818
# Any extensions here not built into Sphinx must also be added to
19-
# the dependencies of //docs/sphinx:sphinx-builder
19+
# the dependencies of //docs:sphinx-builder
2020
extensions = [
2121
"sphinx.ext.autodoc",
2222
"sphinx.ext.autosectionlabel",
@@ -114,7 +114,7 @@
114114
"READTHEDOCS": False,
115115
"PRODUCTION_DOMAIN": "readthedocs.org",
116116
# This is the path to a page's source (after the github user/repo/commit)
117-
"conf_py_path": "/docs/sphinx/",
117+
"conf_py_path": "/docs/",
118118
"github_user": "bazelbuild",
119119
"github_repo": "rules_python",
120120
# The git version that was checked out, e.g. the tag or branch name

‎docs/sphinx/coverage.md renamed to ‎docs/coverage.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/environment-variables.md renamed to ‎docs/environment-variables.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/gazelle.md renamed to ‎docs/gazelle.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/getting-started.md renamed to ‎docs/getting-started.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/glossary.md renamed to ‎docs/glossary.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/index.md renamed to ‎docs/index.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/pip.md renamed to ‎docs/pip.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/precompiling.md renamed to ‎docs/precompiling.md

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/pypi-dependencies.md renamed to ‎docs/pypi-dependencies.md

Copy file name to clipboardExpand all lines: docs/pypi-dependencies.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -324,7 +324,7 @@ the {gh-path}`examples/bzlmod/MODULE.bazel` example.
324324
When using this feature during the `pip` extension evaluation you will see the accessed indexes similar to below:
325325
```console
326326
Loading: 0 packages loaded
327-
currently loading: docs/sphinx
327+
currently loading: docs/
328328
Fetching module extension pip in @@//python/extensions:pip.bzl; starting
329329
Fetching https://pypi.org/simple/twine/
330330
```

‎docs/sphinx/pyproject.toml renamed to ‎docs/pyproject.toml

Copy file name to clipboard
File renamed without changes.

‎docs/sphinx/readthedocs_build.sh renamed to ‎docs/readthedocs_build.sh

Copy file name to clipboardExpand all lines: docs/readthedocs_build.sh
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,4 @@ bazel run \
1717
--config=rtd \
1818
"--//sphinxdocs:extra_defines=version=$READTHEDOCS_VERSION" \
1919
"${extra_env[@]}" \
20-
//docs/sphinx:readthedocs_install
20+
//docs:readthedocs_install

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.