Skip to content

Commit ede4fd4

Browse files
rickeylevrickeylev
authored
docs: initial doc generation using Sphinx (bazel-contrib#1489)
This lays the groundwork for using Sphinx to generate user-facing documentation and having it published on readthedocs. It integrates with Bazel Stardoc to generate MyST-flavored Markdown that Sphinx can process. There are 4 basic pieces that are glued together: 1. `sphinx_docs`: This rule invokes Sphinx to generate e.g. html, latex, etc 2. `sphinx_stardoc`: This rule invokes Stardoc to generate MyST-flavored Markdown that Sphinx can process 3. `sphinx_build_binary`: This rule defines the Sphinx executable with any necessary dependencies (e.g. Sphinx extensions, like MyST) to process the docs in (1) 4. `readthedocs_install`: This rule does the necessary steps to build the docs and put them into the location the readthedocs build process expects. This is basically just `cp -r`, but its cleaner to hide it behind a `bazel run` command than have to put various shell in the readthedocs yaml config. * Bump Bazel 6 requirement: 6.0.0 -> 6.20. This is necessary to support bzlmod and Stardoc. Work towards bazel-contrib#1332, bazel-contrib#1484
1 parent 54d1702 commit ede4fd4

29 files changed

+1606
-6
lines changed

‎.bazelci/presubmit.yml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ buildifier:
2323
# NOTE: Keep in sync with //:version.bzl
2424
bazel: 5.4.0
2525
.minimum_supported_bzlmod_version: &minimum_supported_bzlmod_version
26-
bazel: 6.0.0 # test minimum supported version of bazel for bzlmod tests
26+
bazel: 6.2.0 # test minimum supported version of bazel for bzlmod tests
2727
.reusable_config: &reusable_config
2828
build_targets:
2929
- "--"
@@ -154,8 +154,9 @@ tasks:
154154
# on Bazel 5.4 and earlier. To workaround this, manually specify the
155155
# build kite cc toolchain.
156156
- "--extra_toolchains=@buildkite_config//config:cc-toolchain"
157+
- "--build_tag_filters=-docs"
157158
test_flags:
158-
- "--test_tag_filters=-integration-test,-acceptance-test"
159+
- "--test_tag_filters=-integration-test,-acceptance-test,-docs"
159160
# BazelCI sets --action_env=BAZEL_DO_NOT_DETECT_CPP_TOOLCHAIN=1,
160161
# which prevents cc toolchain autodetection from working correctly
161162
# on Bazel 5.4 and earlier. To workaround this, manually specify the

‎.bazelversion

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
6.0.0
1+
6.2.0

‎.readthedocs.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
2+
version: 2
3+
4+
build:
5+
os: "ubuntu-22.04"
6+
tools:
7+
nodejs: "19"
8+
commands:
9+
- npm install -g @bazel/bazelisk
10+
- bazel run //docs/sphinx:readthedocs_install

‎MODULE.bazel

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,3 +54,16 @@ use_repo(python, "pythons_hub")
5454

5555
# This call registers the Python toolchains.
5656
register_toolchains("@pythons_hub//:all")
57+
58+
# ===== DEV ONLY SETUP =====
59+
docs_pip = use_extension(
60+
"//python/extensions:pip.bzl",
61+
"pip",
62+
dev_dependency = True,
63+
)
64+
docs_pip.parse(
65+
hub_name = "docs_deps",
66+
python_version = "3.11",
67+
requirements_darwin = "//docs/sphinx:requirements_darwin.txt",
68+
requirements_lock = "//docs/sphinx:requirements_linux.txt",
69+
)

‎WORKSPACE

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,11 +84,13 @@ load("@rules_python_gazelle_plugin//:deps.bzl", _py_gazelle_deps = "gazelle_deps
8484
# for python requirements.
8585
_py_gazelle_deps()
8686

87+
# This interpreter is used for various rules_python dev-time tools
88+
load("@python//3.11.6:defs.bzl", "interpreter")
89+
8790
#####################
8891
# Install twine for our own runfiles wheel publishing.
8992
# Eventually we might want to install twine automatically for users too, see:
9093
# https://github.com/bazelbuild/rules_python/issues/1016.
91-
load("@python//3.11.6:defs.bzl", "interpreter")
9294
load("@rules_python//python:pip.bzl", "pip_parse")
9395

9496
pip_parse(
@@ -103,6 +105,21 @@ load("@publish_deps//:requirements.bzl", "install_deps")
103105

104106
install_deps()
105107

108+
#####################
109+
# Install sphinx for doc generation.
110+
111+
pip_parse(
112+
name = "docs_deps",
113+
incompatible_generate_aliases = True,
114+
python_interpreter_target = interpreter,
115+
requirements_darwin = "//docs/sphinx:requirements_darwin.txt",
116+
requirements_lock = "//docs/sphinx:requirements_linux.txt",
117+
)
118+
119+
load("@docs_deps//:requirements.bzl", docs_install_deps = "install_deps")
120+
121+
docs_install_deps()
122+
106123
# This wheel is purely here to validate the wheel extraction code. It's not
107124
# intended for anything else.
108125
http_file(

‎docs/sphinx/BUILD.bazel

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
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+
15+
load("@docs_deps//:requirements.bzl", "requirement")
16+
load("@rules_python//python:pip.bzl", "compile_pip_requirements")
17+
load("//sphinxdocs:readthedocs.bzl", "readthedocs_install")
18+
load("//sphinxdocs:sphinx.bzl", "sphinx_build_binary", "sphinx_docs")
19+
load("//sphinxdocs:sphinx_stardoc.bzl", "sphinx_stardocs")
20+
21+
# We only build for Linux and Mac because the actual doc process only runs
22+
# on Linux. Mac is close enough. Making CI happy under Windows is too much
23+
# of a headache, though, so we don't bother with that.
24+
_TARGET_COMPATIBLE_WITH = select({
25+
"@platforms//os:linux": [],
26+
"@platforms//os:macos": [],
27+
"//conditions:default": ["@platforms//:incompatible"],
28+
})
29+
30+
# See README.md for instructions. Short version:
31+
# * `bazel run //docs/sphinx:docs.serve` in a separate terminal
32+
# * `ibazel build //docs/sphinx:docs` to automatically rebuild docs
33+
sphinx_docs(
34+
name = "docs",
35+
srcs = [
36+
":bzl_api_docs",
37+
] + glob(
38+
include = [
39+
"*.md",
40+
"**/*.md",
41+
"_static/**",
42+
],
43+
exclude = ["README.md"],
44+
),
45+
config = "conf.py",
46+
# Building produces lots of warnings right now because the docs aren't
47+
# entirely ready yet. Silence these to reduce the spam in CI logs.
48+
extra_opts = ["-Q"],
49+
formats = [
50+
"html",
51+
],
52+
sphinx = ":sphinx-build",
53+
strip_prefix = package_name() + "/",
54+
tags = ["docs"],
55+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
56+
)
57+
58+
sphinx_stardocs(
59+
name = "bzl_api_docs",
60+
docs = {
61+
"api/cc/py_cc_toolchain.md": dict(
62+
dep = "//python/private:py_cc_toolchain_bzl",
63+
input = "//python/private:py_cc_toolchain_rule.bzl",
64+
),
65+
"api/cc/py_cc_toolchain_info.md": "//python/cc:py_cc_toolchain_info_bzl",
66+
"api/defs.md": "//python:defs_bzl",
67+
"api/entry_points/py_console_script_binary.md": "//python/entry_points:py_console_script_binary_bzl",
68+
"api/packaging.md": "//python:packaging_bzl",
69+
"api/pip.md": "//python:pip_bzl",
70+
},
71+
tags = ["docs"],
72+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
73+
)
74+
75+
readthedocs_install(
76+
name = "readthedocs_install",
77+
docs = [":docs"],
78+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
79+
)
80+
81+
sphinx_build_binary(
82+
name = "sphinx-build",
83+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
84+
deps = [
85+
requirement("sphinx"),
86+
requirement("sphinx_rtd_theme"),
87+
requirement("myst_parser"),
88+
requirement("readthedocs_sphinx_ext"),
89+
],
90+
)
91+
92+
# Run bazel run //docs/sphinx:requirements.update
93+
compile_pip_requirements(
94+
name = "requirements",
95+
requirements_darwin = "requirements_darwin.txt",
96+
requirements_in = "requirements.in",
97+
requirements_txt = "requirements_linux.txt",
98+
target_compatible_with = _TARGET_COMPATIBLE_WITH,
99+
)

‎docs/sphinx/README.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# rules_python Sphinx docs generation
2+
3+
The docs for rules_python are generated using a combination of Sphinx, Bazel,
4+
and Readthedocs.org. The Markdown files in source control are unlikely to render
5+
properly without the Sphinx processing step because they rely on Sphinx and
6+
MyST-specific Markdown functionality.
7+
8+
The actual sources that Sphinx consumes are in this directory, with Stardoc
9+
generating additional sources or Sphinx.
10+
11+
Manually building the docs isn't necessary -- readthedocs.org will
12+
automatically build and deploy them when commits are pushed to the repo.
13+
14+
## Generating docs for development
15+
16+
Generating docs for development is a two-part process: starting a local HTTP
17+
server to serve the generated HTML, and re-generating the HTML when sources
18+
change. The quick start is:
19+
20+
```
21+
bazel run //docs/sphinx:docs.serve # Run in separate terminal
22+
ibazel build //docs/sphinx:docs # Automatically rebuilds docs
23+
```
24+
25+
This will build the docs and start a local webserver at http://localhost:8000
26+
where you can view the output. As you edit files, ibazel will detect the file
27+
changes and re-run the build process, and you can simply refresh your browser to
28+
see the changes. Using ibazel is not required; you can manually run the
29+
equivalent bazel command if desired.
30+
31+
### Installing ibazel
32+
33+
The `ibazel` tool can be used to automatically rebuild the docs as you
34+
development them. See the [ibazel docs](https://github.com/bazelbuild/bazel-watcher) for
35+
how to install it. The quick start for linux is:
36+
37+
```
38+
sudo apt install npm
39+
sudo npm install -g @bazel/ibazel
40+
```
41+
42+
## MyST Markdown flavor
43+
44+
Sphinx is configured to parse Markdown files using MyST, which is a more
45+
advanced flavor of Markdown that supports most features of restructured text and
46+
integrates with Sphinx functionality such as automatic cross references,
47+
creating indexes, and using concise markup to generate rich documentation.
48+
49+
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.
51+
52+
## Sphinx configuration
53+
54+
The Sphinx-specific configuration files and input doc files live in
55+
docs/sphinx.
56+
57+
The Sphinx configuration is `docs/sphinx/conf.py`. See
58+
https://www.sphinx-doc.org/ for details about the configuration file.
59+
60+
## Readthedocs configuration
61+
62+
There's two basic parts to the readthedocs configuration:
63+
64+
* `.readthedocs.yaml`: This configuration file controls most settings, such as
65+
the OS version used to build, Python version, dependencies, what Bazel
66+
commands to run, etc.
67+
* https://readthedocs.org/projects/rules-python: This is the project
68+
administration page. While most settings come from the config file, this
69+
controls additional settings such as permissions, what versions are
70+
published, when to publish changes, etc.
71+
72+
For more readthedocs configuration details, see docs.readthedocs.io.

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
.wy-nav-content {
2+
max-width: 70%;
3+
}
4+
5+
.starlark-object {
6+
border: thin solid grey;
7+
margin-bottom: 1em;
8+
}
9+
10+
.starlark-object h2 {
11+
background-color: #e7f2fa;
12+
border-bottom: thin solid grey;
13+
padding-left: 0.5ex;
14+
}
15+
16+
.starlark-object>p, .starlark-object>dl {
17+
/* Prevent the words from touching the border line */
18+
padding-left: 0.5ex;
19+
}
20+
21+
.starlark-signature {
22+
font-family: monospace;
23+
}
24+
25+
/* Fixup the headerlinks in param names */
26+
.starlark-object dt a {
27+
/* Offset the link icon to be outside the colon */
28+
position: relative;
29+
right: -1ex;
30+
/* Remove the empty space between the param name and colon */
31+
width: 0;
32+
/* Override the .headerlink margin */
33+
margin-left: 0 !important;
34+
}

‎docs/sphinx/api/index.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# API Reference
2+
3+
```{toctree}
4+
:glob:
5+
**
6+
```

‎docs/sphinx/conf.py

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
3+
# -- Project information
4+
project = "rules_python"
5+
copyright = "2023, The Bazel Authors"
6+
author = "Bazel"
7+
8+
# Readthedocs fills these in
9+
release = "0.0.0"
10+
version = release
11+
12+
# -- General configuration
13+
14+
# Any extensions here not built into Sphinx must also be added to
15+
# the dependencies of Bazel and Readthedocs.
16+
# * //docs:requirements.in
17+
# * Regenerate //docs:requirements.txt (used by readthedocs)
18+
# * Add the dependencies to //docs:sphinx_build
19+
extensions = [
20+
"sphinx.ext.duration",
21+
"sphinx.ext.doctest",
22+
"sphinx.ext.autodoc",
23+
"sphinx.ext.autosummary",
24+
"sphinx.ext.intersphinx",
25+
"sphinx.ext.autosectionlabel",
26+
"myst_parser",
27+
"sphinx_rtd_theme", # Necessary to get jquery to make flyout work
28+
]
29+
30+
exclude_patterns = ["crossrefs.md"]
31+
32+
intersphinx_mapping = {}
33+
34+
intersphinx_disabled_domains = ["std"]
35+
36+
# Prevent local refs from inadvertently linking elsewhere, per
37+
# https://docs.readthedocs.io/en/stable/guides/intersphinx.html#using-intersphinx
38+
intersphinx_disabled_reftypes = ["*"]
39+
40+
templates_path = ["_templates"]
41+
42+
# -- Options for HTML output
43+
44+
html_theme = "sphinx_rtd_theme"
45+
46+
# See https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html
47+
# for options
48+
html_theme_options = {}
49+
50+
# Keep this in sync with the stardoc templates
51+
html_permalinks_icon = "¶"
52+
53+
# See https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
54+
# for additional extensions.
55+
myst_enable_extensions = [
56+
"fieldlist",
57+
"attrs_block",
58+
"attrs_inline",
59+
"colon_fence",
60+
"deflist",
61+
]
62+
63+
# These folders are copied to the documentation's HTML output
64+
html_static_path = ["_static"]
65+
66+
# These paths are either relative to html_static_path
67+
# or fully qualified paths (eg. https://...)
68+
html_css_files = [
69+
"css/custom.css",
70+
]
71+
72+
# -- Options for EPUB output
73+
epub_show_urls = "footnote"

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy