Generate documentation for embedded repository rules Our embedded repository rules have doc strings, as recommended. So far, however, they are not shown on as part of web documentation. Fix this. The recommended tool for generating web pages from Starlark documentation strings is Skydoc; therefore, we use it, even if it pulls in new dependencies, including those that need to be shipped as part of the distribution archive. Fixes #6873. Fixes #7638. Fixes #6730. Change-Id: Icb86cf3c321157e692469b6ed0cac9b64334806c PiperOrigin-RevId: 238958194
diff --git a/WORKSPACE b/WORKSPACE index 3c342cb..22f640d 100644 --- a/WORKSPACE +++ b/WORKSPACE
@@ -106,24 +106,36 @@ archives = [ "e0b0291b2c51fbe5a7cfa14473a1ae850f94f021.zip", "f83cb8dd6f5658bc574ccd873e25197055265d1c.tar.gz", + "java_tools_pkg-0.5.1.tar.gz", "java_tools_javac10_linux-x86_64-v1.0.tar.gz", "java_tools_javac10_windows-x86_64-v1.0.zip", "java_tools_javac10_darwin-v1.0.tar.gz", + "2d9566b21fbe405acf5f7bf77eda30df72a4744c.tar.gz", + "8ccf4f1c351928b55d5dddf3672e3667f6978d60.tar.gz", + "0.16.2.zip", ], dirname = "derived/distdir", sha256 = { "e0b0291b2c51fbe5a7cfa14473a1ae850f94f021.zip": "fe2e04f91ce8c59d49d91b8102edc6627c6fa2906c1b0e7346f01419ec4f419d", "f83cb8dd6f5658bc574ccd873e25197055265d1c.tar.gz": "ba5d15ca230efca96320085d8e4d58da826d1f81b444ef8afccd8b23e0799b52", + "java_tools_pkg-0.5.1.tar.gz": "bcfc1a3dd0d638a49fed50f17f0f1f7d77101debf19ae2c82119c82459a9a8d1", "java_tools_javac10_linux-x86_64-v1.0.tar.gz": "1be7503530ce263f6c90139281f45e9ae4f681a8a362b93ad1ddef4f6db74ce5", "java_tools_javac10_windows-x86_64-v1.0.zip": "15840585eb4db06c2ecc0e14749f96a0e253d9cee2c17b724fc60340d35c6a07", "java_tools_javac10_darwin-v1.0.tar.gz": "a7d292c13c1dbd7def969ddafdf0207a0be5a3e2280fab9164b2c44fd37a82c6", + "2d9566b21fbe405acf5f7bf77eda30df72a4744c.tar.gz": "4a1318fed4831697b83ce879b3ab70ae09592b167e5bda8edaff45132d1c3b3f", + "8ccf4f1c351928b55d5dddf3672e3667f6978d60.tar.gz": "d868ce50d592ef4aad7dec4dd32ae68d2151261913450fac8390b3fd474bb898", + "0.16.2.zip": "9b72bb0aea72d7cbcfc82a01b1e25bf3d85f791e790ddec16c65e2d906382ee0", }, urls = { "e0b0291b2c51fbe5a7cfa14473a1ae850f94f021.zip": ["https://github.com/google/desugar_jdk_libs/archive/e0b0291b2c51fbe5a7cfa14473a1ae850f94f021.zip"], "f83cb8dd6f5658bc574ccd873e25197055265d1c.tar.gz": ["https://github.com/bazelbuild/bazel-skylib/archive/f83cb8dd6f5658bc574ccd873e25197055265d1c.tar.gz"], + "java_tools_pkg-0.5.1.tar.gz": ["https://mirror.bazel.build/bazel_java_tools/java_tools_pkg-0.5.1.tar.gz"], "java_tools_javac10_linux-x86_64-v1.0.tar.gz": ["https://mirror.bazel.build/bazel_java_tools/java_tools_javac10_linux-x86_64-v1.0.tar.gz"], "java_tools_javac10_windows-x86_64-v1.0.zip": ["https://mirror.bazel.build/bazel_java_tools/java_tools_javac10_windows-x86_64-v1.0.zip"], "java_tools_javac10_darwin-v1.0.tar.gz": ["https://mirror.bazel.build/bazel_java_tools/java_tools_javac10_darwin-v1.0.tar.gz"], + "2d9566b21fbe405acf5f7bf77eda30df72a4744c.tar.gz": ["https://github.com/bazelbuild/skydoc/archive/2d9566b21fbe405acf5f7bf77eda30df72a4744c.tar.gz"], + "8ccf4f1c351928b55d5dddf3672e3667f6978d60.tar.gz": ["https://github.com/bazelbuild/rules_sass/archive/8ccf4f1c351928b55d5dddf3672e3667f6978d60.tar.gz" ], + "0.16.2.zip": ["https://github.com/bazelbuild/rules_nodejs/archive/0.16.2.zip"], }, ) @@ -270,8 +282,10 @@ ], ) +# Note that skydoc depends on being called io_bazel_skydoc (and not just skydoc) +# to work without being patched, as it hard-codes this name in its sources. http_archive( - name = "skydoc", + name = "io_bazel_skydoc", sha256 = "4a1318fed4831697b83ce879b3ab70ae09592b167e5bda8edaff45132d1c3b3f", strip_prefix = "skydoc-2d9566b21fbe405acf5f7bf77eda30df72a4744c", urls = [ @@ -351,3 +365,38 @@ sha256 = DOC_VERSION["sha256"], urls = ["https://mirror.bazel.build/bazel_versioned_docs/jekyll-tree-%s.tar" % DOC_VERSION["version"]], ) for DOC_VERSION in DOC_VERSIONS] + +# Skydoc recommends declaring its dependencies via "*_dependencies" functions. +# This requires that the repositories these functions come from need to be +# fetched unconditionally for everything (including just building bazel!), so +# provide them as http_archives that can be shiped in the distdir, to keep the +# distribution archive self-contained. +http_archive( + name = "io_bazel_rules_sass", + strip_prefix = "rules_sass-8ccf4f1c351928b55d5dddf3672e3667f6978d60", + urls = [ + "https://github.com/bazelbuild/rules_sass/archive/8ccf4f1c351928b55d5dddf3672e3667f6978d60.tar.gz", + ], + sha256 = "d868ce50d592ef4aad7dec4dd32ae68d2151261913450fac8390b3fd474bb898", +) +http_archive( + name = "build_bazel_rules_nodejs", + strip_prefix = "rules_nodejs-0.16.2", + urls = [ + "https://github.com/bazelbuild/rules_nodejs/archive/0.16.2.zip", + ], + sha256 = "9b72bb0aea72d7cbcfc82a01b1e25bf3d85f791e790ddec16c65e2d906382ee0", +) + + +load("@io_bazel_skydoc//:setup.bzl", "skydoc_repositories") +skydoc_repositories() + +load("@io_bazel_rules_sass//:package.bzl", "rules_sass_dependencies") +rules_sass_dependencies() + +load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories") +node_repositories() + +load("@io_bazel_rules_sass//:defs.bzl", "sass_repositories") +sass_repositories()
diff --git a/site/BUILD b/site/BUILD index 782c599..bd1c02c 100644 --- a/site/BUILD +++ b/site/BUILD
@@ -135,6 +135,7 @@ "//src/main/java/com/google/devtools/build/lib:gen_buildencyclopedia", "//src/main/java/com/google/devtools/build/lib:gen_skylarklibrary", "//src/main/java/com/google/devtools/build/lib:gen_command-line-reference", + "//tools/build_defs/repo:doc", ], outs = ["jekyll-tree.tar"], cmd = ("$(location jekyll-tree.sh) $@ " + @@ -142,7 +143,8 @@ "$(location :skylark-rule-docs) " + "$(location //src/main/java/com/google/devtools/build/lib:gen_buildencyclopedia) " + "$(location //src/main/java/com/google/devtools/build/lib:gen_skylarklibrary) " + - "$(location //src/main/java/com/google/devtools/build/lib:gen_command-line-reference)"), + "$(location //src/main/java/com/google/devtools/build/lib:gen_command-line-reference) " + + "$(location //tools/build_defs/repo:doc)"), tools = [ "jekyll-tree.sh", ],
diff --git a/site/docs/external.md b/site/docs/external.md index b784e0d..8d9c3bc 100644 --- a/site/docs/external.md +++ b/site/docs/external.md
@@ -42,7 +42,8 @@ This `WORKSPACE` file uses the same syntax as BUILD files, but allows a different set of rules. The full list of built-in rules are in the Build -Encyclopedia's [Workspace Rules](be/workspace.html). +Encyclopedia's [Workspace Rules](be/workspace.html) and the documentation +for [Embedded Starklark Repository Rules](repo/index.html). <a name="types"></a> ## Supported types of external dependencies
diff --git a/site/jekyll-tree.sh b/site/jekyll-tree.sh index 1c2f2ab..20586d2 100755 --- a/site/jekyll-tree.sh +++ b/site/jekyll-tree.sh
@@ -34,6 +34,8 @@ readonly SL_ZIP=${PWD}/$1 shift readonly CLR_HTML=${PWD}/$1 +shift +readonly REPO_ZIP="${PWD}/$1" # Create temporary directory that is removed when this script exits. readonly TMP=$(mktemp -d "${TMPDIR:-/tmp}/tmp.XXXXXXXX") @@ -43,8 +45,7 @@ readonly VERSION="${DOC_VERSION:-master}" readonly VERSION_DIR="$OUT_DIR/versions/$VERSION" -# Unpacks the base Jekyll tree, Build Encyclopedia, Skylark Library, and -# command line reference. +# Unpacks the base Jekyll tree, Build Encyclopedia, etc. function setup { mkdir -p "$OUT_DIR" cd "$OUT_DIR" @@ -66,6 +67,11 @@ unzip -qq "$SL_ZIP" -d "$sl_dir" mv "$sl_dir/skylark-nav.html" "$OUT_DIR/_includes" + # Unpack the the documentation for the repository rules to repo subdirectory + local repo_dir="${VERSION_DIR}/repo" + mkdir -p "${repo_dir}" + unzip -qq "${REPO_ZIP}" -d "${repo_dir}" + # Copy the command line reference. cp "$CLR_HTML" "$VERSION_DIR" }
diff --git a/src/create_embedded_tools.py b/src/create_embedded_tools.py index d1b09ae..dfb7b11 100644 --- a/src/create_embedded_tools.py +++ b/src/create_embedded_tools.py
@@ -29,6 +29,8 @@ output_paths = [ ('*tools/jdk/BUILD', lambda x: 'tools/jdk/BUILD'), + ('*tools/build_defs/repo/BUILD.repo', + lambda x: 'tools/build_defs/repo/BUILD'), ('*tools/platforms/platforms.BUILD', lambda x: 'platforms/BUILD'), ('*tools/platforms/*', lambda x: 'platforms/' + os.path.basename(x)), ('*tools/cpp/runfiles/generated_*',
diff --git a/src/test/java/com/google/devtools/build/skydoc/skydoc_test.bzl b/src/test/java/com/google/devtools/build/skydoc/skydoc_test.bzl index 64188a5..eda5e02 100644 --- a/src/test/java/com/google/devtools/build/skydoc/skydoc_test.bzl +++ b/src/test/java/com/google/devtools/build/skydoc/skydoc_test.bzl
@@ -21,7 +21,7 @@ """Convenience macro for skydoc tests.""" load("@bazel_skylib//:bzl_library.bzl", "bzl_library") -load("@skydoc//stardoc:stardoc.bzl", "stardoc") +load("@io_bazel_skydoc//stardoc:stardoc.bzl", "stardoc") def skydoc_test( name,
diff --git a/src/test/shell/testenv.sh b/src/test/shell/testenv.sh index 7fa8774..8b07c62 100755 --- a/src/test/shell/testenv.sh +++ b/src/test/shell/testenv.sh
@@ -136,6 +136,9 @@ if [ -f tools/jdk/BUILD ]; then chmod +w tools/jdk/BUILD fi + if [ -f tools/build_defs/repo/BUILD.repo ]; then + cp tools/build_defs/repo/BUILD.repo tools/build_defs/repo/BUILD + fi # To support custom langtools cp ${langtools} tools/jdk/langtools.jar cat >>tools/jdk/BUILD <<'EOF'
diff --git a/tools/build_defs/BUILD b/tools/build_defs/BUILD index 456910a..33ab15c 100644 --- a/tools/build_defs/BUILD +++ b/tools/build_defs/BUILD
@@ -15,7 +15,7 @@ "//tools/build_defs/cc:srcs", "//tools/build_defs/hash:srcs", "//tools/build_defs/pkg:srcs", - "//tools/build_defs/repo:srcs", + "//tools/build_defs/repo:embedded_tools", ], visibility = ["//tools:__pkg__"], )
diff --git a/tools/build_defs/repo/BUILD b/tools/build_defs/repo/BUILD index e679a76..fad9c14 100644 --- a/tools/build_defs/repo/BUILD +++ b/tools/build_defs/repo/BUILD
@@ -1,4 +1,5 @@ load("@bazel_skylib//:bzl_library.bzl", "bzl_library") +load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc") licenses(["notice"]) # Apache 2.0 @@ -8,7 +9,22 @@ visibility = ["//tools/build_defs:__pkg__"], ) +filegroup( + name = "embedded_tools", + srcs = glob(["*.bzl"]) + ["BUILD.repo"], + visibility = ["//tools/build_defs:__pkg__"], +) + bzl_library( name = "lib", srcs = glob(["*.bzl"]), ) + +skylark_doc( + name = "doc", + srcs = [":lib"], + format = "html", + site_root = ".", + strip_prefix = "tools/build_defs/repo/", + visibility = ["//site:__subpackages__"], +)
diff --git a/tools/build_defs/repo/BUILD.repo b/tools/build_defs/repo/BUILD.repo new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/tools/build_defs/repo/BUILD.repo