build: generate api docs for all tertiary entry-points (#17293)

Updates our Dgeni setup to generate API docs for all
entry-points which are configured in the `cdk/config.bzl`
or `material/config.bzl` file.

This basically means that we now generate API docs for
`material/*/testing` entry-points and for `cdk/testing/*`.

Removes the code that made `cdk/testing` a separate sub
package. This involves more code than just treating it
as "real" entry-point (for which we generate bundles etc.).

Author: devversion

src/BUILD.bazel

@@ -2,15 +2,17 @@ package(default_visibility = ["//visibility:public"])
 
 load("@npm_bazel_typescript//:index.bzl", "ts_config")
 load("//src/cdk:config.bzl", "CDK_ENTRYPOINTS")
-load("//src/material:config.bzl", "MATERIAL_ENTRYPOINTS")
+load("//src/material:config.bzl", "MATERIAL_ENTRYPOINTS", "MATERIAL_TESTING_ENTRYPOINTS")
 load("//tools:defaults.bzl", "ts_library")
 load("//tools/dgeni:index.bzl", "dgeni_api_docs")
 
+cdkApiEntryPoints = CDK_ENTRYPOINTS
+
+materialApiEntryPoints = MATERIAL_ENTRYPOINTS + MATERIAL_TESTING_ENTRYPOINTS
+
 # List that contains all source files that need to be processed by Dgeni.
-apiSourceFiles = ["//src/cdk/%s:source-files" % name for name in CDK_ENTRYPOINTS] + [
-    "//src/material/%s:source-files" % name
-    for name in MATERIAL_ENTRYPOINTS
-]
+apiSourceFiles = ["//src/cdk/%s:source-files" % name for name in cdkApiEntryPoints] + \
+                 ["//src/material/%s:source-files" % name for name in materialApiEntryPoints]
 
 exports_files([
     "bazel-tsconfig-build.json",
@@ -42,8 +44,8 @@ dgeni_api_docs(
         "@npm//@angular/platform-browser",
     ],
     entry_points = {
-        "cdk": CDK_ENTRYPOINTS,
-        "material": MATERIAL_ENTRYPOINTS,
+        "cdk": cdkApiEntryPoints,
+        "material": materialApiEntryPoints,
     },
     tags = ["docs-package"],
 )

src/cdk/BUILD.bazel

@@ -57,13 +57,14 @@ ng_package(
     entry_point = ":public-api.ts",
     packages = [
         "//src/cdk/schematics:npm_package",
-        "//src/cdk/testing:npm_package",
     ],
     tags = ["release-package"],
     deps = CDK_TARGETS,
 )
 
 filegroup(
     name = "overviews",
-    srcs = ["//src/cdk/%s:overview" % name for name in CDK_ENTRYPOINTS],
+    # Only secondary entry-points declare overview files currently. Entry-points
+    # which contain a slash are not in the top-level and do not have an overview.
+    srcs = ["//src/cdk/%s:overview" % ep for ep in CDK_ENTRYPOINTS if not "/" in ep],
 )

src/cdk/config.bzl

@@ -18,13 +18,12 @@ CDK_ENTRYPOINTS = [
     "text-field",
     "tree",
     "testing",
+    "testing/protractor",
+    "testing/testbed",
 ]
 
-# List of all entry-point targets of the Angular Material package. Note that
-# we do not want to include "testing" here as it will be treated as a standalone
-# sub-package of the "ng_package".
-CDK_TARGETS = ["//src/cdk"] + \
-              ["//src/cdk/%s" % ep for ep in CDK_ENTRYPOINTS if not ep == "testing"]
+# List of all entry-point targets of the Angular Material package.
+CDK_TARGETS = ["//src/cdk"] + ["//src/cdk/%s" % ep for ep in CDK_ENTRYPOINTS]
 
 # Within the CDK, only a few targets have sass libraries which need to be
 # part of the release package. This list declares all CDK targets with sass

src/cdk/testing/BUILD.bazel

@@ -1,6 +1,5 @@
 package(default_visibility = ["//visibility:public"])
 
-load("@build_bazel_rules_nodejs//:defs.bzl", "npm_package")
 load("//src/e2e-app:test_suite.bzl", "e2e_test_suite")
 load("//tools:defaults.bzl", "markdown_to_html", "ng_web_test_suite", "ts_library")
 
@@ -15,15 +14,6 @@ ts_library(
     module_name = "@angular/cdk/testing",
 )
 
-npm_package(
-    name = "npm_package",
-    deps = [
-        ":testing",
-        "//src/cdk/testing/protractor",
-        "//src/cdk/testing/testbed",
-    ],
-)
-
 markdown_to_html(
     name = "overview",
     srcs = ["testing.md"],

src/cdk/testing/protractor/BUILD.bazel

@@ -14,3 +14,8 @@ ts_library(
         "@npm//protractor",
     ],
 )
+
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)

src/cdk/testing/testbed/BUILD.bazel

@@ -15,3 +15,8 @@ ts_library(
         "@npm//@angular/core",
     ],
 )
+
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)

src/material/autocomplete/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/button/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/checkbox/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/dialog/testing/BUILD.bazel

@@ -16,6 +16,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/menu/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/progress-bar/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/progress-spinner/testing/BUILD.bazel

@@ -16,6 +16,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/radio/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/sidenav/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/slide-toggle/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/slider/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/snack-bar/testing/BUILD.bazel

@@ -14,6 +14,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

src/material/tabs/testing/BUILD.bazel

@@ -15,6 +15,11 @@ ts_library(
     ],
 )
 
+filegroup(
+    name = "source-files",
+    srcs = glob(["**/*.ts"]),
+)
+
 ng_test_library(
     name = "harness_tests_lib",
     srcs = ["shared.spec.ts"],

tools/dgeni/bazel-bin.ts

@@ -4,6 +4,7 @@ import {TsParser} from 'dgeni-packages/typescript/services/TsParser';
 import {readFileSync} from 'fs';
 import {join, relative} from 'path';
 import {apiDocsPackage} from './docs-package';
+import {EntryPointGrouper} from './processors/entry-point-grouper';
 
 /**
  * Determines the command line arguments for the current Bazel action. Since this action can
@@ -39,6 +40,7 @@ if (require.main === module) {
   // Configure the Dgeni docs package to respect our passed options from the Bazel rule.
   apiDocsPackage.config(function(readTypeScriptModules: ReadTypeScriptModules,
                                  tsParser: TsParser,
+                                 entryPointGrouper: EntryPointGrouper,
                                  templateFinder: any,
                                  writeFilesProcessor: any,
                                  readFilesProcessor: any) {
@@ -73,6 +75,7 @@ if (require.main === module) {
         const entryPointPath = `${packageName}/${entryPointName}`;
         const entryPointIndexPath = `${entryPointPath}/index.ts`;
 
+        entryPointGrouper.entryPoints.push(entryPointPath);
         tsParser.options.paths![`@angular/${entryPointPath}`] = [entryPointIndexPath];
         readTypeScriptModules.sourceFiles.push(entryPointIndexPath);
       });

tools/dgeni/common/class-inheritance.ts

@@ -0,0 +1,16 @@
+import {ClassLikeExportDoc} from 'dgeni-packages/typescript/api-doc-types/ClassLikeExportDoc';
+
+/** Gets all class like export documents which the given doc inherits from. */
+export function getInheritedDocsOfClass(doc: ClassLikeExportDoc): ClassLikeExportDoc[] {
+  const directBaseDocs = [
+    ...doc.implementsClauses.filter(clause => clause.doc).map(d => d.doc!),
+    ...doc.extendsClauses.filter(clause => clause.doc).map(d => d.doc!),
+  ];
+
+  return [
+    ...directBaseDocs,
+    // recursively collect base documents of direct base documents.
+    ...directBaseDocs.reduce(
+      (res: ClassLikeExportDoc[], d) => res.concat(getInheritedDocsOfClass(d)), []),
+  ];
+}

tools/dgeni/common/decorators.ts

@@ -42,10 +42,10 @@ export function isDeprecatedDoc(doc: any) {
   return (doc.tags && doc.tags.tags || []).some((tag: any) => tag.tagName === 'deprecated');
 }
 
-/** Whether the given document is annotated with the "@docs-primary-module" jsdoc tag. */
-export function isPrimaryModuleDoc(doc: any) {
+/** Whether the given document is annotated with the "@docs-primary-export" jsdoc tag. */
+export function isPrimaryExportDoc(doc: any) {
   return (doc.tags && doc.tags.tags || [])
-      .some((tag: any) => tag.tagName === 'docs-primary-module');
+      .some((tag: any) => tag.tagName === 'docs-primary-export');
 }
 
 export function getDirectiveSelectors(classDoc: CategorizedClassDoc) {

tools/dgeni/common/dgeni-definitions.ts

@@ -30,10 +30,12 @@ export interface CategorizedClassDoc extends ClassExportDoc, CategorizedClassLik
   isDirective: boolean;
   isService: boolean;
   isNgModule: boolean;
+  isTestHarness: boolean;
   directiveExportAs?: string | null;
   directiveSelectors?: string[];
   directiveMetadata: Map<string, any> | null;
   extendedDoc: ClassLikeExportDoc | undefined;
+  inheritedDocs: ClassLikeExportDoc[];
 }
 
 /** Extended Dgeni property-member document that includes extracted Angular metadata. */

tools/dgeni/docs-package.ts

@@ -79,7 +79,7 @@ apiDocsPackage.config(function(parseTagsProcessor: any) {
   parseTagsProcessor.tagDefinitions = parseTagsProcessor.tagDefinitions.concat([
     {name: 'docs-private'},
     {name: 'docs-public'},
-    {name: 'docs-primary-module'},
+    {name: 'docs-primary-export'},
     {name: 'breaking-change'},
   ]);
 });

tools/dgeni/index.bzl

@@ -40,8 +40,9 @@ def _dgeni_api_docs(ctx):
             expected_outputs += [
                 # Declare the output for the current entry-point. The output file will always follow the
                 # same format: "{output_folder}/{package_name}-{entry_point_name}.html"
-                # (e.g. "api-docs/material-slider.html")
-                ctx.actions.declare_file("%s/%s-%s.html" % (output_dir_name, package_name, entry_point)),
+                # (e.g. "api-docs/material-slider-testing.html")
+                ctx.actions.declare_file("%s/%s-%s.html" %
+                                         (output_dir_name, package_name, entry_point.replace("/", "-"))),
             ]
 
         # Small workaround that ensures that the "ripple" API doc is properly exposed as an output