docs(bazel): add skydoc generation (angular#23544)

PR Close angular#23544

Author: alexeagle

WORKSPACE

@@ -38,6 +38,13 @@ http_archive(
     sha256 = "feba3278c13cde8d67e341a837f69a029f698d7a27ddbb2a202be7a10b22142a",
 )
 
+http_archive(
+    name = "io_bazel_rules_sass",
+    url = "https://github.com/bazelbuild/rules_sass/archive/0.1.0.zip",
+    strip_prefix = "rules_sass-0.1.0",
+    sha256 = "b243c4d64f054c174051785862ab079050d90b37a1cef7da93821c6981cb9ad4",
+)
+
 # This commit matches the version of buildifier in angular/ngcontainer
 # If you change this, also check if it matches the version in the angular/ngcontainer
 # version in /.circleci/config.yml
@@ -58,6 +65,14 @@ http_archive(
     sha256 = "e373d2ae24955c1254c495c9c421c009d88966565c35e4e8444c082cb1f0f48f",
 )
 
+http_archive(
+    name = "io_bazel_skydoc",
+    # TODO: switch to upstream when https://github.com/bazelbuild/skydoc/pull/103 is merged
+    url = "https://github.com/alexeagle/skydoc/archive/fe2e9f888d28e567fef62ec9d4a93c425526d701.zip",
+    strip_prefix = "skydoc-fe2e9f888d28e567fef62ec9d4a93c425526d701",
+    sha256 = "7bfb5545f59792a2745f2523b9eef363f9c3e7274791c030885e7069f8116016",
+)
+
 # We have a source dependency on the Devkit repository, because it's built with
 # Bazel.
 # This allows us to edit sources and have the effect appear immediately without
@@ -144,3 +159,12 @@ yarn_install(
     package_json = "//tools/http-server:package.json",
     yarn_lock = "//tools/http-server:yarn.lock",
 )
+
+##################################
+# Skylark documentation generation
+
+load("@io_bazel_rules_sass//sass:sass_repositories.bzl", "sass_repositories")
+sass_repositories()
+
+load("@io_bazel_skydoc//skylark:skylark.bzl", "skydoc_repositories")
+skydoc_repositories()

packages/bazel/BUILD.bazel

@@ -14,6 +14,7 @@ npm_package(
         "package.json",
         "//packages/bazel/src:package_assets",
     ],
+    packages = ["//packages/bazel/docs"],
     # Re-host //packages/bazel/ which is just // in the public distro
     replacements = {
         "//packages/bazel/": "//",

packages/bazel/docs/BUILD.bazel

@@ -0,0 +1,16 @@
+load("@io_bazel_skydoc//skylark:skylark.bzl", "skylark_doc")
+
+skylark_doc(
+    name = "docs",
+    srcs = [
+        "//packages/bazel/src:ng_module.bzl",
+        "//packages/bazel/src:ng_rollup_bundle.bzl",
+        "//packages/bazel/src:ng_setup_workspace.bzl",
+        "//packages/bazel/src/ng_package:ng_package.bzl",
+        "//packages/bazel/src/protractor:protractor_web_test.bzl",
+    ],
+    format = "html",
+    site_root = "/bazel-builds",
+    strip_prefix = "packages/bazel/",
+    visibility = ["//packages/bazel:__subpackages__"],
+)

packages/bazel/index.bzl

@@ -19,3 +19,5 @@ ng_package = _ng_package
 protractor_web_test = _protractor_web_test
 protractor_web_test_suite = _protractor_web_test_suite
 ng_setup_workspace = _ng_setup_workspace
+# DO NOT ADD PUBLIC API without including in the documentation generation
+# Run `bazel build //packages/bazel/docs` to verify

packages/bazel/src/ng_module.bzl

@@ -2,7 +2,7 @@
 #
 # Use of this source code is governed by an MIT-style license that can be
 # found in the LICENSE file at https://angular.io/license
-"""Implementation of the ng_module rule.
+"""Run Angular's AOT template compiler
 """
 
 load(":rules_typescript.bzl",
@@ -453,13 +453,21 @@ def _ng_module_impl(ctx):
 NG_MODULE_ATTRIBUTES = {
     "srcs": attr.label_list(allow_files = [".ts"]),
 
-    "deps": attr.label_list(aspects = DEPS_ASPECTS + [_collect_summaries_aspect]),
+    # Note: DEPS_ASPECTS is already a list, we add the cast to workaround
+    # https://github.com/bazelbuild/skydoc/issues/21
+    "deps": attr.label_list(
+        doc = "Targets that are imported by this target",
+        aspects = list(DEPS_ASPECTS) + [_collect_summaries_aspect]
+    ),
 
-    "assets": attr.label_list(allow_files = [
-      ".css",
-      # TODO(alexeagle): change this to ".ng.html" when usages updated
-      ".html",
-    ]),
+    "assets": attr.label_list(
+        doc = ".html and .css files needed by the Angular compiler",
+        allow_files = [
+            ".css",
+            # TODO(alexeagle): change this to ".ng.html" when usages updated
+            ".html",
+        ],
+    ),
 
     "factories": attr.label_list(
         allow_files = [".ts", ".html"],
@@ -515,7 +523,13 @@ ng_module = rule(
     attrs = NG_MODULE_RULE_ATTRS,
     outputs = COMMON_OUTPUTS,
 )
+"""
+Run the Angular AOT template compiler.
 
+This rule extends the [ts_library] rule.
+
+[ts_library]: http://tsetse.info/api/build_defs.html#ts_library
+"""
 
 # TODO(alxhub): this rule causes legacy ngc to produce Ivy outputs from global analysis information.
 # It exists to facilitate testing of the Ivy runtime until ngtsc is mature enough to be used

packages/bazel/src/ng_package/ng_package.bzl

@@ -2,7 +2,15 @@
 #
 # Use of this source code is governed by an MIT-style license that can be
 # found in the LICENSE file at https://angular.io/license
-"""Implementation of the ng_package rule.
+"""Package Angular libraries for npm distribution
+
+If all users of an Angular library use Bazel (e.g. internal usage in your company)
+then you should simply add your library to the `deps` of the consuming application.
+
+These rules exist for compatibility with non-Bazel consumers of your library.
+
+It packages your library following the Angular Package Format, see the
+specification of this format at https://goo.gl/jB3GVv
 """
 
 load("@build_bazel_rules_nodejs//:internal/collect_es6_sources.bzl", "collect_es6_sources")
@@ -352,6 +360,18 @@ NG_PACKAGE_ATTRS = dict(NPM_PACKAGE_ATTRS, **dict(ROLLUP_ATTRS, **{
 # some/path/to/my/package/index.js
 # we assume the files should be named "package.*.js"
 def primary_entry_point_name(name, entry_point, entry_point_name):
+  """This is not a public API.
+
+  Compute the name of the primary entry point in the library.
+
+  Args:
+    name: the name of the `ng_package` rule, as a fallback.
+    entry_point: The starting point of the application, see rollup_bundle.
+    entry_point_name: if set, this is the returned value.
+
+  Returns:
+    name of the entry point, which will appear in the name of generated bundles
+  """
   if entry_point_name:
       # If an explicit entry_point_name is given, use that.
       return entry_point_name
@@ -364,6 +384,19 @@ def primary_entry_point_name(name, entry_point, entry_point_name):
       return name
 
 def ng_package_outputs(name, entry_point, entry_point_name):
+  """This is not a public API.
+
+  This function computes the named outputs for an ng_package rule.
+
+  Args:
+    name: value of the name attribute
+    entry_point: value of the entry_point attribute
+    entry_point_name: value of the entry_point_name attribute
+
+  Returns:
+    dict of named outputs of the rule
+  """
+
   basename = primary_entry_point_name(name, entry_point, entry_point_name)
   outputs = {
       "fesm5": "fesm5/%s.js" % basename,
@@ -384,3 +417,6 @@ ng_package = rule(
     attrs = NG_PACKAGE_ATTRS,
     outputs = ng_package_outputs,
 )
+"""
+ng_package produces an npm-ready package from an Angular library.
+"""

packages/bazel/src/ng_rollup_bundle.bzl

@@ -3,11 +3,15 @@
 # Use of this source code is governed by an MIT-style license that can be
 # found in the LICENSE file at https://angular.io/license
 
-"""This provides a variant of rollup_bundle that works better for Angular apps.
+"""Rollup with Build Optimizer
 
-   It registers @angular-devkit/build-optimizer as a rollup plugin, to get
+   This provides a variant of the [rollup_bundle] rule that works better for Angular apps.
+
+   It registers `@angular-devkit/build-optimizer` as a rollup plugin, to get
    better optimization. It also uses ESM5 format inputs, as this is what
    build-optimizer is hard-coded to look for and transform.
+
+   [rollup_bundle]: https://bazelbuild.github.io/rules_nodejs/rollup/rollup_bundle.html
 """
 
 load("@build_bazel_rules_nodejs//internal/rollup:rollup_bundle.bzl",
@@ -51,6 +55,13 @@ def _use_plain_rollup(ctx):
 
 
 def run_brotli(ctx, input, output):
+  """Execute the Brotli compression utility.
+
+  Args:
+    ctx: Bazel's rule execution context
+    input: any file
+    output: the compressed file
+  """
   ctx.actions.run(
       executable = ctx.executable._brotli,
       inputs = [input],
@@ -126,10 +137,14 @@ def _ng_rollup_bundle(ctx):
 ng_rollup_bundle = rule(
     implementation = _ng_rollup_bundle,
     attrs = dict(ROLLUP_ATTRS, **{
-        "deps": attr.label_list(aspects = [
-            rollup_module_mappings_aspect,
-            esm5_outputs_aspect,
-        ]),
+        "deps": attr.label_list(
+            doc = """Other targets that provide JavaScript files.
+            Typically this will be `ts_library` or `ng_module` targets.""",
+            aspects = [
+                rollup_module_mappings_aspect,
+                esm5_outputs_aspect,
+            ]
+        ),
         "_rollup": attr.label(
             executable = True,
             cfg = "host",
@@ -143,3 +158,13 @@ ng_rollup_bundle = rule(
         "build_es5_min_compressed": "%{name}.min.js.br",
     }),
 )
+"""
+Run [Rollup] with the [Build Optimizer] plugin.
+
+This rule extends from the [rollup_bundle] rule, so attributes and outputs of
+that rule are used here too.
+
+[Rollup]: https://rollupjs.org/
+[Build Optimizer]: https://www.npmjs.com/package/@angular-devkit/build-optimizer
+[rollup_bundle]: https://bazelbuild.github.io/rules_nodejs/rollup/rollup_bundle.html
+"""

packages/bazel/src/protractor/protractor_web_test.bzl

@@ -2,8 +2,7 @@
 #
 # Use of this source code is governed by an MIT-style license that can be
 # found in the LICENSE file at https://angular.io/license
-"""Implementation of the protractor_web_test and protractor_web_test_suite rules.
-"""
+"Run end-to-end tests with Protractor"
 
 load("@build_bazel_rules_nodejs//internal:node.bzl",
     "sources_aspect",