diff --git a/WORKSPACE b/WORKSPACE index dad470331a..8077a0e15b 100644 --- a/WORKSPACE +++ b/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() diff --git a/packages/bazel/BUILD.bazel b/packages/bazel/BUILD.bazel index c4d4b06428..282edb9a40 100644 --- a/packages/bazel/BUILD.bazel +++ b/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/": "//", diff --git a/packages/bazel/docs/BUILD.bazel b/packages/bazel/docs/BUILD.bazel new file mode 100644 index 0000000000..234fb875da --- /dev/null +++ b/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__"], +) diff --git a/packages/bazel/index.bzl b/packages/bazel/index.bzl index ebf756931f..227cb984dc 100644 --- a/packages/bazel/index.bzl +++ b/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 diff --git a/packages/bazel/src/ng_module.bzl b/packages/bazel/src/ng_module.bzl index be0ef7a001..8026c61e09 100644 --- a/packages/bazel/src/ng_module.bzl +++ b/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 diff --git a/packages/bazel/src/ng_package/ng_package.bzl b/packages/bazel/src/ng_package/ng_package.bzl index 3350bb4cfd..b9603ed573 100644 --- a/packages/bazel/src/ng_package/ng_package.bzl +++ b/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. +""" \ No newline at end of file diff --git a/packages/bazel/src/ng_rollup_bundle.bzl b/packages/bazel/src/ng_rollup_bundle.bzl index b90c7e5942..8ee1c3a26d 100644 --- a/packages/bazel/src/ng_rollup_bundle.bzl +++ b/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 +""" \ No newline at end of file diff --git a/packages/bazel/src/protractor/protractor_web_test.bzl b/packages/bazel/src/protractor/protractor_web_test.bzl index 3b66c4ee32..ae404885a7 100644 --- a/packages/bazel/src/protractor/protractor_web_test.bzl +++ b/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",