Skip to content

Commit 93d8b0a

Browse files
brandjonbrandjon
authored
Migrate to stardoc and regenerate documentation (bazel-contrib#213)
* Upgrade documentation generation to Stardoc This was a long time coming. Our previous Skydoc workflow no longer worked, and Skydoc has been deprecated for a while. This commit updates the WORKSPACE deps for Stardoc, and rewrites the docgen workflow in docs/BUILD and update_docs.sh. Note that running the workflow requires some visibility changes to @bazel_tools, which will be in Bazel 0.29. Fixes bazel-contrib#144. * Regenerate documentation using Stardoc This rips out the old documentation, which was malformed and unreproducible, and adds documentation generated by Stardoc. It was generated using a development version of Bazel that makes some @bazel_tools targets publically visible. These changes will be in Bazel 0.29. Follow-up for bazel-contrib#144. * Exclude docs/ from CI config The new docgen workflow requires Bazel 0.29, which is currently unreleased. This commit excludes the docgen from being tested on CI. We'll undo this after 0.29 is released (bazel-contrib#144).
1 parent 522222a commit 93d8b0a

18 files changed

Lines changed: 428 additions & 1034 deletions

File tree

‎.bazelci/presubmit.yml‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,36 @@
1+
# We exclude docs/ from build_targets. Since we can't blacklist specific target
2+
# patterns (bazelbuild/continuous-integration#779), we have to explicitly
3+
# list every other top-level package in build_targets.
4+
# TODO(#144): When Bazel 0.29 is released, the docgen workflow will work, and
5+
# we can go back to using `...` for build_targets.
16
---
27
platforms:
38
ubuntu1604:
9+
# I don't trust my knowledge of YAML enough to factor this list into an
10+
# anchor.
411
build_targets:
5-
- "..."
12+
- "//examples/..."
13+
- "//experimental/..."
14+
- "//python/..."
15+
- "//rules_python/..."
16+
- "//tools/..."
617
test_targets:
718
- "..."
819
ubuntu1804:
920
build_targets:
10-
- "..."
21+
- "//examples/..."
22+
- "//experimental/..."
23+
- "//python/..."
24+
- "//rules_python/..."
25+
- "//tools/..."
1126
test_targets:
1227
- "..."
1328
macos:
1429
build_targets:
15-
- "..."
30+
- "//examples/..."
31+
- "//experimental/..."
32+
- "//python/..."
33+
- "//rules_python/..."
34+
- "//tools/..."
1635
test_targets:
1736
- "..."

‎WORKSPACE‎

Lines changed: 11 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -17,49 +17,31 @@ workspace(name = "rules_python")
1717
load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
1818
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")
1919

20-
################################
21-
# Skydoc and its dependencies. #
22-
################################
20+
#################################
21+
# Stardoc and its dependencies. #
22+
#################################
2323

24-
# Skydoc's sass dependency is not covered by skydoc_repositories(), so we have
25-
# to redeclare it here. Watch that the version matches when updating Skydoc's
26-
# version.
24+
# Initialization taken from:
25+
# https://skydoc.bazel.build/docs/getting_started_stardoc.html
2726

2827
git_repository(
29-
name = "io_bazel_rules_sass",
30-
# Same commit as Skydoc uses in its own WORKSPACE.
31-
commit = "8ccf4f1c351928b55d5dddf3672e3667f6978d60", # 2018-11-23
32-
remote = "https://github.com/bazelbuild/rules_sass.git",
28+
name = "io_bazel_skydoc",
29+
remote = "https://github.com/bazelbuild/skydoc.git",
30+
tag = "0.3.0",
3331
)
3432

35-
load("@io_bazel_rules_sass//:package.bzl", "rules_sass_dependencies")
33+
load("@io_bazel_skydoc//:setup.bzl", "skydoc_repositories")
34+
skydoc_repositories()
3635

36+
load("@io_bazel_rules_sass//:package.bzl", "rules_sass_dependencies")
3737
rules_sass_dependencies()
3838

39-
# Node is used by sass. This weird (anti-?)pattern of initializing a repo we
40-
# didn't directly import is taken from Skydoc's WORKSPACE.
4139
load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories")
42-
4340
node_repositories()
4441

4542
load("@io_bazel_rules_sass//:defs.bzl", "sass_repositories")
46-
4743
sass_repositories()
4844

49-
# We implicitly depend on Skydoc importing Skylib under `@bazel_skylib`.
50-
# We don't redeclare it here in order to avoid repeating a definition that
51-
# could get out of sync with Skydoc.
52-
53-
git_repository(
54-
name = "io_bazel_skydoc",
55-
commit = "1cdb612e31448c2f6eb25b8aa67d406152275482", # 2018-11-27
56-
remote = "https://github.com/bazelbuild/skydoc.git",
57-
)
58-
59-
load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories")
60-
61-
skydoc_repositories()
62-
6345
##########################################
6446
# Requirements for building our piptool. #
6547
##########################################

‎docs/BUILD‎

Lines changed: 42 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -11,51 +11,60 @@
1111
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1212
# See the License for the specific language governing permissions and
1313
# limitations under the License.
14+
15+
###############################################################################
16+
# To regenerate documentation, run the top-level update_docs.sh script. #
17+
###############################################################################
18+
1419
package(default_visibility = ["//visibility:public"])
1520

1621
licenses(["notice"]) # Apache 2.0
1722

18-
# To regenerate html docs, run:
19-
# ./update_docs.sh
23+
load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
24+
load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc")
2025

21-
load("@bazel_skylib//:skylark_library.bzl", "skylark_library")
22-
load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc")
26+
# We define these bzl_library targets here rather than in the //python package
27+
# because they're only used for doc generation. This way, we avoid requiring
28+
# our users to depend on Skylib.
2329

24-
skylark_library(
25-
name = "whl",
26-
srcs = ["//python:whl.bzl"],
30+
# Requires Bazel 0.29 onward for public visibility of these .bzl files.
31+
bzl_library(
32+
name = "bazel_python_tools",
33+
srcs = [
34+
"@bazel_tools//tools/python:srcs_version.bzl",
35+
"@bazel_tools//tools/python:toolchain.bzl",
36+
"@bazel_tools//tools/python:utils.bzl",
37+
],
2738
)
2839

29-
skylark_library(
30-
name = "pip",
31-
srcs = ["//python:pip.bzl"],
40+
bzl_library(
41+
name = "defs",
42+
srcs = [
43+
"//python:defs.bzl",
44+
"//python:private/reexports.bzl",
45+
],
46+
deps = [":bazel_python_tools"],
3247
)
3348

34-
skylark_library(
35-
name = "python",
36-
srcs = ["//python:python.bzl"],
49+
stardoc(
50+
name = "core-docs",
51+
input = "//python:defs.bzl",
52+
out = "python.md",
53+
deps = [":defs"],
3754
)
3855

39-
skylark_doc(
40-
name = "docs-md",
41-
format = "markdown",
42-
overview = True,
43-
site_root = ".",
44-
deps = [
45-
":pip",
46-
":python",
47-
":whl",
48-
],
56+
# TODO: Consider merging documentation pages for whl and pip. This would
57+
# require re-exporting their symbols from a common .bzl; see
58+
# https://github.com/bazelbuild/skydoc/issues/208.
59+
60+
stardoc(
61+
name = "pip-docs",
62+
input = "//python:pip.bzl",
63+
out = "pip.md",
4964
)
5065

51-
skylark_doc(
52-
name = "docs-html",
53-
format = "html",
54-
overview = True,
55-
site_root = ".",
56-
deps = [
57-
":pip",
58-
":python",
59-
":whl",
60-
],
66+
stardoc(
67+
name = "whl-docs",
68+
input = "//python:whl.bzl",
69+
out = "whl.md",
6170
)

‎docs/index.html‎

Lines changed: 0 additions & 195 deletions
This file was deleted.

0 commit comments

Comments
 (0)