Skip to content

Commit 509b02f

Browse files
rickeylevaignas
rickeylev
and
aignas
authored
docs: use stardoc proto output to generate markdown docs (bazel-contrib#1629)
The template language Stardoc uses (Velocity) is niche and fairly esoteric, and requires a lot of experimenting to understand how to make it produce the desired output. In particular, it largely assumes whitespace doesn't matter, which makes it a poor fit for generating Markdown, where whitespace often does matter. Instead, a small Python program is used to consume the binary proto output of Stardoc, which converts it to Markdown. This also makes it easier to customize the overall output and re-use code for the different types of objects rendered. The visible changes to the docs are: * Module extensions are now documented * Repository rules follow the style of the other generated docs * Fixed the rendering of pip_repository docs -- it had an h2 section which broke the section grouping of the API objects. * Puts some padding between the border and content for text in params/attrs/fields listings. Other notable changes: * Make RTD builds use bzlmod. This is necessary so that the pip extension can be documented. It loads `@pythons_hub//:interpreters.bzl`, but that repo is only created when bzlmod is enabled) --------- Co-authored-by: Ignas Anikevicius <240938+aignas@users.noreply.github.com>
1 parent 87a3a54 commit 509b02f

25 files changed

Lines changed: 928 additions & 200 deletions

‎.bazelrc‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,5 +25,8 @@ startup --windows_enable_symlinks
2525
common --noexperimental_enable_bzlmod
2626

2727
# Additional config to use for readthedocs builds.
28-
# See .readthedocs.yml for additional flags
28+
# See .readthedocs.yml for additional flags that can only be determined from
29+
# the runtime environment.
2930
build:rtd --stamp
31+
# Some bzl files contain repos only available under bzlmod
32+
build:rtd --enable_bzlmod

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,10 @@ A brief description of the categories of changes:
4747
* (bzlmod pip.parse) Requirements files with duplicate entries for the same
4848
package (e.g. one for the package, one for an extra) now work.
4949

50+
### Added
51+
52+
* (docs) bzlmod extensions are now documented on rules-python.readthedocs.io
53+
5054
[0.XX.0]: https://github.com/bazelbuild/rules_python/releases/tag/0.XX.0
5155

5256
## [0.27.0] - 2023-11-16

‎MODULE.bazel‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,12 +56,12 @@ use_repo(python, "pythons_hub")
5656
register_toolchains("@pythons_hub//:all")
5757

5858
# ===== DEV ONLY SETUP =====
59-
docs_pip = use_extension(
59+
dev_pip = use_extension(
6060
"//python/extensions:pip.bzl",
6161
"pip",
6262
dev_dependency = True,
6363
)
64-
docs_pip.parse(
64+
dev_pip.parse(
6565
experimental_requirement_cycles = {
6666
"sphinx": [
6767
"sphinx",
@@ -72,7 +72,7 @@ docs_pip.parse(
7272
"sphinxcontrib-applehelp",
7373
],
7474
},
75-
hub_name = "docs_deps",
75+
hub_name = "dev_pip",
7676
python_version = "3.11",
7777
requirements_darwin = "//docs/sphinx:requirements_darwin.txt",
7878
requirements_lock = "//docs/sphinx:requirements_linux.txt",

‎WORKSPACE‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,7 @@ install_deps()
109109
# Install sphinx for doc generation.
110110

111111
pip_parse(
112-
name = "docs_deps",
112+
name = "dev_pip",
113113
experimental_requirement_cycles = {
114114
"sphinx": [
115115
"sphinx",
@@ -126,7 +126,7 @@ pip_parse(
126126
requirements_lock = "//docs/sphinx:requirements_linux.txt",
127127
)
128128

129-
load("@docs_deps//:requirements.bzl", docs_install_deps = "install_deps")
129+
load("@dev_pip//:requirements.bzl", docs_install_deps = "install_deps")
130130

131131
docs_install_deps()
132132

@@ -140,3 +140,9 @@ http_file(
140140
"https://files.pythonhosted.org/packages/50/67/3e966d99a07d60a21a21d7ec016e9e4c2642a86fea251ec68677daf71d4d/numpy-1.25.2-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl",
141141
],
142142
)
143+
144+
# rules_proto expects //external:python_headers to point at the python headers.
145+
bind(
146+
name = "python_headers",
147+
actual = "//python/cc:current_py_cc_headers",
148+
)

‎docs/sphinx/BUILD.bazel‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,10 @@
1212
# See the License for the specific language governing permissions and
1313
# limitations under the License.
1414

15-
load("@docs_deps//:requirements.bzl", "requirement")
16-
load("@rules_python//python:pip.bzl", "compile_pip_requirements")
15+
load("@dev_pip//:requirements.bzl", "requirement")
16+
load("//python:pip.bzl", "compile_pip_requirements")
17+
load("//python/private:bzlmod_enabled.bzl", "BZLMOD_ENABLED") # buildifier: disable=bzl-visibility
18+
load("//python/private:util.bzl", "IS_BAZEL_7_OR_HIGHER") # buildifier: disable=bzl-visibility
1719
load("//sphinxdocs:readthedocs.bzl", "readthedocs_install")
1820
load("//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs", "sphinx_inventory")
1921
load("//sphinxdocs:sphinx_stardoc.bzl", "sphinx_stardocs")
@@ -83,7 +85,13 @@ sphinx_stardocs(
8385
"api/entry_points/py_console_script_binary.md": "//python/entry_points:py_console_script_binary_bzl",
8486
"api/packaging.md": "//python:packaging_bzl",
8587
"api/pip.md": "//python:pip_bzl",
86-
},
88+
} | ({
89+
# Bazel 6 + Stardoc isn't able to parse something about the python bzlmod extension
90+
"api/extensions/python.md": "//python/extensions:python_bzl",
91+
} if IS_BAZEL_7_OR_HIGHER else {}) | ({
92+
# This depends on @pythons_hub, which is only created under bzlmod
93+
"api/extensions/pip.md": "//python/extensions:pip_bzl",
94+
} if BZLMOD_ENABLED else {}),
8795
footer = "_stardoc_footer.md",
8896
tags = ["docs"],
8997
target_compatible_with = _TARGET_COMPATIBLE_WITH,

‎docs/sphinx/_stardoc_footer.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
[`Label`]: https://bazel.build/rules/lib/Label
88
[`list`]: https://bazel.build/rules/lib/list
99
[`str`]: https://bazel.build/rules/lib/string
10+
[str]: https://bazel.build/rules/lib/string
11+
[`int`]: https://bazel.build/rules/lib/int
1012
[`struct`]: https://bazel.build/rules/lib/builtins/struct
1113
[`Target`]: https://bazel.build/rules/lib/Target
1214
[target-name]: https://bazel.build/concepts/labels#target-names

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

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,17 @@
1212
border-bottom: thin solid grey;
1313
padding-left: 0.5ex;
1414
}
15+
.starlark-object h3 {
16+
background-color: #e7f2fa;
17+
padding-left: 0.5ex;
18+
}
19+
20+
.starlark-module-extension-tag-class h3 {
21+
background-color: #add8e6;
22+
padding-left: 0.5ex;
23+
}
1524

16-
.starlark-object>p, .starlark-object>dl {
25+
.starlark-object>p, .starlark-object>dl, .starlark-object>section>* {
1726
/* Prevent the words from touching the border line */
1827
padding-left: 0.5ex;
1928
}

‎docs/sphinx/pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,5 @@ dependencies = [
99
"myst-parser",
1010
"sphinx_rtd_theme",
1111
"readthedocs-sphinx-ext",
12+
"absl-py",
1213
]

‎docs/sphinx/readthedocs_build.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ extra_env+=("--//sphinxdocs:extra_env=HOSTNAME=$HOSTNAME")
1414

1515
set -x
1616
bazel run \
17+
--config=rtd \
1718
"--//sphinxdocs:extra_defines=version=$READTHEDOCS_VERSION" \
1819
"${extra_env[@]}" \
1920
//docs/sphinx:readthedocs_install

‎docs/sphinx/requirements_linux.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@
44
#
55
# bazel run //docs/sphinx:requirements.update
66
#
7+
absl-py==2.0.0 \
8+
--hash=sha256:9a28abb62774ae4e8edbe2dd4c49ffcd45a6a848952a5eccc6a49f3f0fc1e2f3 \
9+
--hash=sha256:d9690211c5fcfefcdd1a45470ac2b5c5acd45241c3af71eed96bc5441746c0d5
10+
# via rules-python-docs (docs/sphinx/pyproject.toml)
711
alabaster==0.7.13 \
812
--hash=sha256:1ee19aca801bbabb5ba3f5f258e4422dfa86f82f3e9cefb0859b283cdd7f62a3 \
913
--hash=sha256:a27a4a084d5e690e16e01e03ad2b2e552c61a65469419b907243193de1a84ae2

0 commit comments

Comments
 (0)