feat(aio): first pass API docs redesign (#21874)

Includes:

* display ToC for API docs
* update dgeni-packages to 0.24.1
* add floating sidebar in API docs
* add breadcrumbs and structured data for Google crawler
* improved rendering of method overloads
* properties rendered in a table
* params rendered with docs
* removal of outdated "infobox" from all API docs

PR Close #21874

aio/tools/transforms/angular-api-package/index.js

@@ -21,7 +21,9 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
   .processor(require('./processors/extractDecoratedClasses'))
   .processor(require('./processors/matchUpDirectiveDecorators'))
   .processor(require('./processors/addMetadataAliases'))
+  .processor(require('./processors/computeApiBreadCrumbs'))
   .processor(require('./processors/filterContainedDocs'))
+  .processor(require('./processors/processClassLikeMembers'))
   .processor(require('./processors/markBarredODocsAsPrivate'))
   .processor(require('./processors/filterPrivateDocs'))
   .processor(require('./processors/computeSearchTitle'))
@@ -86,15 +88,6 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
     // Load up all the tag definitions in the tag-defs folder
     parseTagsProcessor.tagDefinitions =
         parseTagsProcessor.tagDefinitions.concat(getInjectables(requireFolder(__dirname, './tag-defs')));
-
-    // We actually don't want to parse param docs in this package as we are getting the data out using TS
-    // TODO: rewire the param docs to the params extracted from TS
-    parseTagsProcessor.tagDefinitions.forEach(function(tagDef) {
-      if (tagDef.name === 'param') {
-        tagDef.docProperty = 'paramData';
-        tagDef.transforms = [];
-      }
-    });
   })
 
 

aio/tools/transforms/angular-api-package/processors/computeApiBreadCrumbs.js

@@ -0,0 +1,19 @@
+module.exports = function computeApiBreadCrumbs(EXPORT_DOC_TYPES) {
+  return {
+    $runAfter: ['paths-computed'],
+    $runBefore: ['rendering-docs'],
+    $process(docs) {
+      // Compute the breadcrumb for each doc by processing its containers
+      docs.forEach(doc => {
+        if (EXPORT_DOC_TYPES.indexOf(doc.docType) !== -1) {
+          doc.breadCrumbs = [
+            { text: 'API', path: '/api' },
+            { text: '@angular/' + doc.moduleDoc.id, path: doc.moduleDoc.path },
+            { text: doc.name, path: doc.path }
+          ];
+        }
+      });
+    }
+  };
+};
+

aio/tools/transforms/angular-api-package/processors/computeApiBreadCrumbs.spec.js

@@ -0,0 +1,39 @@
+const testPackage = require('../../helpers/test-package');
+const processorFactory = require('./computeApiBreadCrumbs');
+const Dgeni = require('dgeni');
+
+describe('angular-api-package: computeApiBreadCrumbs processor', () => {
+
+  it('should be available on the injector', () => {
+    const dgeni = new Dgeni([testPackage('angular-api-package')]);
+    const injector = dgeni.configureInjector();
+    const processor = injector.get('computeApiBreadCrumbs');
+    expect(processor.$process).toBeDefined();
+    expect(processor.$runAfter).toEqual(['paths-computed']);
+    expect(processor.$runBefore).toEqual(['rendering-docs']);
+  });
+
+  it('should attach a breadCrumbs property to each of the EXPORT_DOC_TYPES docs', () => {
+    const EXPORT_DOC_TYPES = ['class', 'interface'];
+    const processor = processorFactory(EXPORT_DOC_TYPES);
+
+    const docs = [
+      { docType: 'class', name: 'ClassA', path: 'module-1/class-a', moduleDoc: { id: 'moduleOne', path: 'module-1' } },
+      { docType: 'interface', name: 'InterfaceB', path: 'module-2/interface-b', moduleDoc: { id: 'moduleTwo', path: 'module-2' } },
+      { docType: 'guide', name: 'Guide One', path: 'guide/guide-1' },
+    ];
+    processor.$process(docs);
+
+    expect(docs[0].breadCrumbs).toEqual([
+      { text: 'API', path: '/api' },
+      { text: '@angular/moduleOne', path: 'module-1' },
+      { text: 'ClassA', path: 'module-1/class-a' },
+    ]);
+    expect(docs[1].breadCrumbs).toEqual([
+      { text: 'API', path: '/api' },
+      { text: '@angular/moduleTwo', path: 'module-2' },
+      { text: 'InterfaceB', path: 'module-2/interface-b' },
+    ]);
+    expect(docs[2].breadCrumbs).toBeUndefined();
+  });
+});

aio/tools/transforms/angular-api-package/processors/processClassLikeMembers.js

@@ -0,0 +1,59 @@
+/**
+ * A class like API doc contains members, but these can be either properties or method.
+ * Separate the members into two new collections: `doc.properties` and `doc.methods`.
+ */
+module.exports = function processClassLikeMembers() {
+  return {
+    $runAfter: ['filterContainedDocs'],
+    $runBefore: ['rendering-docs'],
+    $process(docs) {
+      docs.forEach(doc => {
+        if (doc.members) {
+          doc.properties = [];
+          doc.methods = [];
+          doc.members.forEach(member => {
+            if (isMethod(member)) {
+              doc.methods.push(member);
+              computeMemberDescription(member);
+            } else {
+              doc.properties.push(member);
+
+              if (!member.description) {
+                // Is this property defined as a constructor parameter e.g. `constructor(public property: string) { ... }`?
+                const constructorDoc = member.containerDoc.constructorDoc;
+                if (constructorDoc) {
+                  const matchingParameterDoc = constructorDoc.parameterDocs.filter(doc => doc.declaration === member.declaration)[0];
+                  member.constructorParamDoc = matchingParameterDoc;
+                }
+              }
+            }
+          });
+        }
+        if (doc.statics) {
+          doc.staticProperties = [];
+          doc.staticMethods = [];
+          doc.statics.forEach(member => {
+            if (isMethod(member)) {
+              doc.staticMethods.push(member);
+              computeMemberDescription(member);
+            } else {
+              doc.staticProperties.push(member);
+            }
+          });
+        }
+
+      });
+    }
+  };
+};
+
+function isMethod(doc) {
+  return doc.hasOwnProperty('parameters') && !doc.isGetAccessor && !doc.isSetAccessor;
+}
+
+function computeMemberDescription(member) {
+  if (!member.description && member.overloads) {
+    // Perhaps the description is on one of the overloads - take the first non-empty one
+    member.description = member.overloads.map(overload => overload.description).filter(description => !!description)[0];
+  }
+}

aio/tools/transforms/angular-api-package/processors/processClassLikeMembers.spec.js

@@ -0,0 +1,81 @@
+const testPackage = require('../../helpers/test-package');
+const processorFactory = require('./processClassLikeMembers');
+const Dgeni = require('dgeni');
+
+const property1 = { description: 'property 1' };
+const property2 = { description: 'property 2' };
+const getter1 = { parameters: [], isGetAccessor: true, description: 'getter 1' };
+const setter1 = { parameters: [], isSetAccessor: true, description: 'setter 1' };
+const method1 = { parameters: [] };
+const method2 = { parameters: [] };
+const method3 = { parameters: [] };
+
+describe('angular-api-packge: processClassLikeMembers processor', () => {
+
+  it('should be available on the injector', () => {
+    const dgeni = new Dgeni([testPackage('angular-api-package')]);
+    const injector = dgeni.configureInjector();
+    const processor = injector.get('processClassLikeMembers');
+    expect(processor.$process).toBeDefined();
+    expect(processor.$runAfter).toEqual(['filterContainedDocs']);
+    expect(processor.$runBefore).toEqual(['rendering-docs']);
+  });
+
+  it('should copy instance members into properties and methods', () => {
+    const processor = processorFactory();
+    const docs = [
+      { members: [ property1, method1, getter1] },
+      { members: [ method2, property2, method3, setter1] },
+      { }
+    ];
+    processor.$process(docs);
+
+    expect(docs[0].properties).toEqual([property1, getter1]);
+    expect(docs[0].methods).toEqual([method1]);
+
+    expect(docs[1].properties).toEqual([property2, setter1]);
+    expect(docs[1].methods).toEqual([method2, method3]);
+
+    expect(docs[2].properties).toBeUndefined();
+    expect(docs[2].methods).toBeUndefined();
+  });
+
+  it('should copy static members into properties and methods', () => {
+    const processor = processorFactory();
+    const docs = [
+      { statics: [ property1, method1, getter1] },
+      { statics: [ method2, property2, method3, setter1] },
+      { }
+    ];
+    processor.$process(docs);
+
+    expect(docs[0].staticProperties).toEqual([property1, getter1]);
+    expect(docs[0].staticMethods).toEqual([method1]);
+
+    expect(docs[1].staticProperties).toEqual([property2, setter1]);
+    expect(docs[1].staticMethods).toEqual([method2, method3]);
+
+    expect(docs[2].staticProperties).toBeUndefined();
+    expect(docs[2].staticMethods).toBeUndefined();
+  });
+
+  it('should wire up properties that are declared as parameters on the constructor to its associated parameter doc', () => {
+    const processor = processorFactory();
+    const propertyDeclaration = {};
+    const parameterDoc1 = { declaration: {} };
+    const parameterDoc2 = { declaration: propertyDeclaration };
+    const parameterDoc3 = { declaration: {} };
+    const property = {
+      declaration: propertyDeclaration,
+      containerDoc: {
+        constructorDoc: {
+          parameterDocs: [ parameterDoc1, parameterDoc2, parameterDoc3 ]
+        }
+      }
+    };
+    const docs = [{ members: [ property] }];
+    processor.$process(docs);
+
+    expect(property.constructorParamDoc).toEqual(parameterDoc2);
+  });
+});

aio/tools/transforms/angular-api-package/tag-defs/throws.js

@@ -0,0 +1,8 @@
+module.exports = function(extractTypeTransform, wholeTagTransform) {
+  return {
+    name: 'throws',
+    aliases: ['exception'],
+    multi: true,
+    transforms: [ extractTypeTransform, wholeTagTransform ]
+  };
+};