Reorganized sub-workspace dependencies (#398)

This pull request contains various cleanup/quality-of-life improvements for the repository by clearly grouping and defining dependencies for the docs and examples workspaces. Ultimately, the files that are created in here can be moved entirely into their neighboring WORKSPACE files once bazelbuild/bazel#1943 has been closed.

Author: UebelAndre

.bazelignore

@@ -0,0 +1,11 @@
+# Docs
+docs/bazel-bin
+docs/bazel-docs
+docs/bazel-out
+docs/bazel-testlogs
+
+# Examples
+examples/bazel-bin
+examples/bazel-examples
+examples/bazel-out
+examples/bazel-testlogs

WORKSPACE

@@ -3,31 +3,18 @@ workspace(name = "io_bazel_rules_rust")
 load("@bazel_tools//tools/build_defs/repo:git.bzl", "new_git_repository")
 load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
-local_repository(
-    name = "examples",
-    path = "examples",
-)
-
-local_repository(
-    name = "docs",
-    path = "docs",
-)
-
 http_archive(
     name = "bazel_skylib",
+    sha256 = "1c531376ac7e5a180e0237938a2536de0c54d93f5c278634818e0efc952dd56c",
     urls = [
         "https://github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz",
         "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz",
     ],
-    sha256 = "1c531376ac7e5a180e0237938a2536de0c54d93f5c278634818e0efc952dd56c",
 )
 
 load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
-bazel_skylib_workspace()
 
-# TODO: Move this to examples/WORKSPACE when recursive repositories are enabled.
-load("@io_bazel_rules_rust//rust:repositories.bzl", "rust_repositories")
-rust_repositories()
+bazel_skylib_workspace()
 
 new_git_repository(
     name = "libc",
@@ -37,43 +24,26 @@ new_git_repository(
 )
 
 load("@io_bazel_rules_rust//proto:repositories.bzl", "rust_proto_repositories")
+
 rust_proto_repositories()
 
 load("@io_bazel_rules_rust//bindgen:repositories.bzl", "rust_bindgen_repositories")
+
 rust_bindgen_repositories()
 
 load("@io_bazel_rules_rust//wasm_bindgen:repositories.bzl", "rust_wasm_bindgen_repositories")
-rust_wasm_bindgen_repositories()
-
-http_archive(
-    name = "build_bazel_rules_nodejs",
-    sha256 = "e1a0d6eb40ec89f61a13a028e7113aa3630247253bcb1406281b627e44395145",
-    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/1.0.1/rules_nodejs-1.0.1.tar.gz"],
-)
-
-load("@build_bazel_rules_nodejs//:index.bzl", "node_repositories", "npm_install")
-node_repositories()
 
-# Dependencies for the @examples//hello_world_wasm example.
-npm_install(
-    name = "npm",
-    package_json = "//:package.json",
-    package_lock_json = "//:package-lock.json",
-)
-
-# Install all Bazel dependencies needed for npm packages that supply Bazel rules
-load("@npm//:install_bazel_dependencies.bzl", "install_bazel_dependencies")
+rust_wasm_bindgen_repositories()
 
-install_bazel_dependencies()
 # --- end stardoc
 
 http_archive(
     name = "bazel_toolchains",
     sha256 = "d8c2f20deb2f6143bac792d210db1a4872102d81529fe0ea3476c1696addd7ff",
     strip_prefix = "bazel-toolchains-0.28.3",
     urls = [
-      "https://mirror.bazel.build/github.com/bazelbuild/bazel-toolchains/archive/0.28.3.tar.gz",
-      "https://github.com/bazelbuild/bazel-toolchains/archive/0.28.3.tar.gz",
+        "https://mirror.bazel.build/github.com/bazelbuild/bazel-toolchains/archive/0.28.3.tar.gz",
+        "https://github.com/bazelbuild/bazel-toolchains/archive/0.28.3.tar.gz",
     ],
 )
 
@@ -86,7 +56,43 @@ rbe_autoconfig(
 )
 
 load("@io_bazel_rules_rust//:workspace.bzl", "bazel_version")
+
 bazel_version(name = "bazel_version")
 
+# Load all dependencies for examples
+
+local_repository(
+    name = "examples",
+    path = "examples",
+)
+
+load("@examples//:examples_repositories.bzl", examples_repositories = "repositories")
+
+examples_repositories()
+
+load("@examples//:examples_deps.bzl", examples_deps = "deps")
+
+examples_deps()
+
+load("@examples//:examples_extra_deps.bzl", examples_extra_deps = "extra_deps")
+
+examples_extra_deps()
+
 load("@examples//hello_sys:workspace.bzl", "remote_deps")
+
 remote_deps()
+
+# Load all dependencies for docs
+
+local_repository(
+    name = "docs",
+    path = "docs",
+)
+
+load("@docs//:docs_repositories.bzl", docs_repositories = "repositories")
+
+docs_repositories()
+
+load("@docs//:docs_deps.bzl", docs_deps = "deps")
+
+docs_deps(is_top_level = True)

docs/BUILD

@@ -1,8 +1,8 @@
-package(default_visibility = ["//visibility:private"])
-
 load("@io_bazel_stardoc//stardoc:stardoc.bzl", "stardoc")
 load("@bazel_skylib//:bzl_library.bzl", "bzl_library")
 
+package(default_visibility = ["//visibility:private"])
+
 bzl_library(
     name = "all_deps",
     srcs = [
@@ -21,11 +21,30 @@ bzl_library(
 )
 
 PAGES = {
-    "rust": ["rust_library", "rust_binary", "rust_benchmark", "rust_test"],
-    "rust_doc": ["rust_doc", "rust_doc_test"],
-    "rust_proto": ["rust_proto_toolchain","rust_proto_library", "rust_grpc_library"],
-    "rust_bindgen": ["rust_bindgen_toolchain","rust_bindgen_library", "rust_bindgen"],
-    "rust_wasm_bindgen": ["rust_wasm_bindgen_toolchain","rust_wasm_bindgen"],
+    "rust": [
+        "rust_library",
+        "rust_binary",
+        "rust_benchmark",
+        "rust_test",
+    ],
+    "rust_doc": [
+        "rust_doc",
+        "rust_doc_test",
+    ],
+    "rust_proto": [
+        "rust_proto_toolchain",
+        "rust_proto_library",
+        "rust_grpc_library",
+    ],
+    "rust_bindgen": [
+        "rust_bindgen_toolchain",
+        "rust_bindgen_library",
+        "rust_bindgen",
+    ],
+    "rust_wasm_bindgen": [
+        "rust_wasm_bindgen_toolchain",
+        "rust_wasm_bindgen",
+    ],
     "cargo_build_script": ["cargo_build_script"],
 }
 
@@ -34,7 +53,8 @@ PAGES = {
         name = "%s_header_vm" % k,
         outs = ["%s_header.vm" % k],
         cmd = ">$@ echo '# Rust rules\n%s'" % "\n".join(
-            ["* [{rule}](#{rule})".format(rule=v) for v in PAGES[k]]),
+            ["* [{rule}](#{rule})".format(rule = v) for v in PAGES[k]],
+        ),
         output_to_bindir = True,
     )
     for k in PAGES.keys()
@@ -44,25 +64,28 @@ PAGES = {
     stardoc(
         name = "%s_md" % k,
         out = "%s.md" % k,
+        header_template = ":%s_header_vm" % k,
         input = ":all.bzl",
         symbol_names = PAGES[k],
-        header_template = ":%s_header_vm" % k,
         deps = [":all_deps"],
     )
     for k in PAGES.keys()
 ]
+
 genrule(
-        name = "flatten_header_vm",
-        outs = ["flatten_header.vm"],
-        cmd = ">$@ echo '# Rust rules\n\n%s\n'" % "\n".join(
-            ["* [{rule}](#{rule})".format(rule=v) for k in PAGES.keys() for v in PAGES[k]]),
-        output_to_bindir = True,
+    name = "flatten_header_vm",
+    outs = ["flatten_header.vm"],
+    cmd = ">$@ echo '# Rust rules\n\n%s\n'" % "\n".join(
+        ["* [{rule}](#{rule})".format(rule = v) for k in PAGES.keys() for v in PAGES[k]],
+    ),
+    output_to_bindir = True,
 )
+
 stardoc(
     name = "flatten_md",
-    out  = "flatten.md",
+    out = "flatten.md",
     header_template = ":flatten_header_vm",
     input = ":all.bzl",
     symbol_names = [symbol for k in PAGES.keys() for symbol in PAGES[k]],
     deps = [":all_deps"],
-)
+)

docs/WORKSPACE

@@ -1,45 +1,9 @@
 workspace(name = "io_bazel_rules_rust_docs")
-load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 
-local_repository(
-    name = "io_bazel_rules_rust",
-    path = "..",
-)
+load(":docs_repositories.bzl", "repositories")
 
-http_archive(
-    name = "bazel_skylib",
-    urls = [
-        "https://github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz",
-        "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz",
-    ],
-    sha256 = "1c531376ac7e5a180e0237938a2536de0c54d93f5c278634818e0efc952dd56c",
-)
+repositories()
 
-load("@bazel_skylib//:workspace.bzl", "bazel_skylib_workspace")
-bazel_skylib_workspace()
+load(":docs_deps.bzl", "deps")
 
-http_archive(
-    name = "io_bazel_stardoc",
-    urls = [
-        "https://github.com/bazelbuild/stardoc/archive/1ef781ced3b1443dca3ed05dec1989eca1a4e1cd.zip",
-    ],
-    sha256 = "5d7191bb0800434a9192d8ac80cba4909e96dbb087c5d51f168fedd7bde7b525",
-    strip_prefix = "stardoc-1ef781ced3b1443dca3ed05dec1989eca1a4e1cd",
-)
-
-load("@io_bazel_rules_rust//rust:repositories.bzl", "rust_repositories")
-load("@io_bazel_rules_rust//proto:repositories.bzl", "rust_proto_repositories")
-load("@io_bazel_rules_rust//:workspace.bzl", "bazel_version")
-load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
-
-rust_repositories()
-rust_proto_repositories()
-bazel_version(name = "bazel_version")
-stardoc_repositories()
-
-# Rules proto does not declare a bzl_library, we stub it there for now.
-# TODO: Remove this hack if/when rules_proto adds a bzl_library.
-local_repository(
-    name = "rules_proto",
-    path = "rules_proto_stub",
-)
+deps()

docs/docs_deps.bzl

@@ -0,0 +1,34 @@
+"""Define dependencies for `rules_rust` docs"""
+
+load("@io_bazel_rules_rust//rust:repositories.bzl", "rust_repositories")
+load("@io_bazel_rules_rust//proto:repositories.bzl", "rust_proto_repositories")
+load("@io_bazel_rules_rust//:workspace.bzl", "bazel_version")
+load("@io_bazel_stardoc//:setup.bzl", "stardoc_repositories")
+load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
+
+def deps(is_top_level = False):
+    """Define dependencies for `rules_rust` docs
+
+    Args:
+        is_top_level (bool, optional): Indicates wheather or not this is being called
+            from the root WORKSPACE file of `rules_rust`. Defaults to False.
+    """
+    rust_repositories()
+    rust_proto_repositories()
+    bazel_version(name = "bazel_version")
+    stardoc_repositories()
+
+    # Rules proto does not declare a bzl_library, we stub it there for now.
+    # TODO: Remove this hack if/when rules_proto adds a bzl_library.
+    if is_top_level:
+        maybe(
+            native.local_repository,
+            name = "rules_proto",
+            path = "docs/rules_proto_stub",
+        )
+    else:
+        maybe(
+            native.local_repository,
+            name = "rules_proto",
+            path = "rules_proto_stub",
+        )

docs/docs_repositories.bzl

@@ -0,0 +1,37 @@
+"""Define repository dependencies for `rules_rust` docs"""
+
+load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
+load("@bazel_tools//tools/build_defs/repo:utils.bzl", "maybe")
+
+def repositories(is_top_level = False):
+    """Define repository dependencies for `rules_rust` docs
+
+    Args:
+        is_top_level (bool, optional): Indicates wheather or not this is being called
+            from the root WORKSPACE file of `rules_rust`. Defaults to False.
+    """
+    maybe(
+        native.local_repository,
+        name = "io_bazel_rules_rust",
+        path = "..",
+    )
+
+    maybe(
+        http_archive,
+        name = "bazel_skylib",
+        sha256 = "1c531376ac7e5a180e0237938a2536de0c54d93f5c278634818e0efc952dd56c",
+        urls = [
+            "https://github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz",
+            "https://mirror.bazel.build/github.com/bazelbuild/bazel-skylib/releases/download/1.0.3/bazel-skylib-1.0.3.tar.gz",
+        ],
+    )
+
+    maybe(
+        http_archive,
+        name = "io_bazel_stardoc",
+        urls = [
+            "https://github.com/bazelbuild/stardoc/archive/1ef781ced3b1443dca3ed05dec1989eca1a4e1cd.zip",
+        ],
+        sha256 = "5d7191bb0800434a9192d8ac80cba4909e96dbb087c5d51f168fedd7bde7b525",
+        strip_prefix = "stardoc-1ef781ced3b1443dca3ed05dec1989eca1a4e1cd",
+    )

docs/update_docs.sh

@@ -1,6 +1,13 @@
 #!/bin/bash
 
 pushd ${0%/*}
-bazel build //... && cp bazel-bin/*.md . && chmod 0644 *.md && git add *.md && git commit -m "Regenerate documentation"
+# It's important to clean the workspace so we don't end up with unintended
+# docs artifacts in the new commit.
+bazel clean \
+&& bazel build //... \
+&& cp bazel-bin/*.md . \
+&& chmod 0644 *.md \
+&& git add *.md \
+&& git commit -m "Regenerate documentation"
 popd