bazel-contrib · brandjon · Jul 28, 2019 · Jul 22, 2019 · Jul 22, 2019 · Jul 28, 2019
diff --git a/.bazelci/presubmit.yml b/.bazelci/presubmit.yml
@@ -1,17 +1,36 @@
+# We exclude docs/ from build_targets. Since we can't blacklist specific target
+# patterns (bazelbuild/continuous-integration#779), we have to explicitly
+# list every other top-level package in build_targets.
+# TODO(#144): When Bazel 0.29 is released, the docgen workflow will work, and
+# we can go back to using `...` for build_targets.
 ---
 platforms:
  ubuntu1604:
+    # I don't trust my knowledge of YAML enough to factor this list into an
+    # anchor.
    build_targets:
-    - "..."
+    - "//examples/..."
+    - "//experimental/..."
+    - "//python/..."
+    - "//rules_python/..."
+    - "//tools/..."
    test_targets:
    - "..."
  ubuntu1804:
    build_targets:
-    - "..."
+    - "//examples/..."
+    - "//experimental/..."
+    - "//python/..."
+    - "//rules_python/..."
+    - "//tools/..."
    test_targets:
    - "..."
  macos:
    build_targets:
-    - "..."
+    - "//examples/..."
+    - "//experimental/..."
+    - "//python/..."
+    - "//rules_python/..."
+    - "//tools/..."
    test_targets:
    - "..."
diff --git a/WORKSPACE b/WORKSPACE
@@ -17,49 +17,31 @@ workspace(name = "rules_python")
 load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository")
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_file")

-################################
-# Skydoc and its dependencies. #
-################################
+#################################
+# Stardoc and its dependencies. #
+#################################

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

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

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

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

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

 load("@io_bazel_rules_sass//:defs.bzl", "sass_repositories")
-
 sass_repositories()

-# We implicitly depend on Skydoc importing Skylib under `@bazel_skylib`.
-# We don't redeclare it here in order to avoid repeating a definition that
-# could get out of sync with Skydoc.
-
-git_repository(
-    name = "io_bazel_skydoc",
-    commit = "1cdb612e31448c2f6eb25b8aa67d406152275482",  # 2018-11-27
-    remote = "https://github.com/bazelbuild/skydoc.git",
-)
-
-load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories")
-
-skydoc_repositories()
-
 ##########################################
 # Requirements for building our piptool. #
 ##########################################

diff --git a/docs/BUILD b/docs/BUILD
@@ -11,51 +11,60 @@
 # 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.
+
+###############################################################################
+# To regenerate documentation, run the top-level update_docs.sh script.       #
+###############################################################################
+
 package(default_visibility = ["//visibility:public"])

 licenses(["notice"])  # Apache 2.0

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

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

-skylark_library(
-    name = "whl",
-    srcs = ["//python:whl.bzl"],
+# Requires Bazel 0.29 onward for public visibility of these .bzl files.
+bzl_library(
+    name = "bazel_python_tools",
+    srcs = [
+        "@bazel_tools//tools/python:srcs_version.bzl",
+        "@bazel_tools//tools/python:toolchain.bzl",
+        "@bazel_tools//tools/python:utils.bzl",
+    ],
 )

-skylark_library(
-    name = "pip",
-    srcs = ["//python:pip.bzl"],
+bzl_library(
+    name = "defs",
+    srcs = [
+        "//python:defs.bzl",
+        "//python:private/reexports.bzl",
+    ],
+    deps = [":bazel_python_tools"],
 )

-skylark_library(
-    name = "python",
-    srcs = ["//python:python.bzl"],
+stardoc(
+    name = "core-docs",
+    input = "//python:defs.bzl",
+    out = "python.md",
+    deps = [":defs"],
 )

-skylark_doc(
-    name = "docs-md",
-    format = "markdown",
-    overview = True,
-    site_root = ".",
-    deps = [
-        ":pip",
-        ":python",
-        ":whl",
-    ],
+# TODO: Consider merging documentation pages for whl and pip. This would
+# require re-exporting their symbols from a common .bzl; see
+# https://github.com/bazelbuild/skydoc/issues/208.
+
+stardoc(
+    name = "pip-docs",
+    input = "//python:pip.bzl",
+    out = "pip.md",
 )

-skylark_doc(
-    name = "docs-html",
-    format = "html",
-    overview = True,
-    site_root = ".",
-    deps = [
-        ":pip",
-        ":python",
-        ":whl",
-    ],
+stardoc(
+    name = "whl-docs",
+    input = "//python:whl.bzl",
+    out = "whl.md",
 )
diff --git a/docs/index.html b/docs/index.html