build(docs-infra): separate NgModules from Classes in API docs (#25734)

PR Close #25734

aio/src/app/custom-elements/api/api-list.component.ts

@@ -49,6 +49,7 @@ export class ApiListComponent implements OnInit {
     { value: 'function', title: 'Function' },
     { value: 'interface', title: 'Interface' },
     { value: 'pipe', title: 'Pipe'},
+    { value: 'ngmodule', title: 'NgModule'},
     { value: 'type-alias', title: 'Type alias' },
     { value: 'package', title: 'Package'}
   ];

aio/src/styles/_constants.scss

@@ -61,6 +61,14 @@ $api-symbols: (
     content: ' ',
     background: $white
   ),
+  class: (
+    content: 'C',
+    background: $blue-500
+  ),
+  const: (
+    content: 'K',
+    background: $mediumgray
+  ),
   decorator: (
     content: '@',
     background: $blue-800
@@ -69,46 +77,42 @@ $api-symbols: (
     content: 'D',
     background: $pink-600
   ),
-  pipe: (
+  enum: (
-    content: 'P',
+    content: 'E',
-    background: $blue-grey-600
+    background: $amber-700
-  ),
-  class: (
-    content: 'C',
-    background: $blue-500
-  ),
-  interface: (
-    content: 'I',
-    background: $teal-500
   ),
   function: (
     content: 'F',
     background: $green-500
   ),
-  enum: (
+  interface: (
-    content: 'E',
+    content: 'I',
-    background: $amber-700
+    background: $teal-500
-  ),
-  const: (
-    content: 'K',
-    background: $mediumgray
   ),
   let: (
     content: 'K',
     background: $mediumgray
   ),
-  var: (
+  ngmodule: (
-    content: 'K',
+    content: 'M',
-    background: $mediumgray
+    background: $darkred
+  ),
+  package: (
+    content: 'Pk',
+    background: $purple-600
+  ),
+  pipe: (
+    content: 'P',
+    background: $blue-grey-600
   ),
   type-alias: (
     content: 'T',
     background: $light-green-600
   ),
-  package: (
+  var: (
-    content: 'Pk',
+    content: 'K',
-    background: $purple-600
+    background: $mediumgray
-  )
+  ),
 );
 
 // OTHER

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

@@ -34,6 +34,8 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
   .processor(require('./processors/computeStability'))
   .processor(require('./processors/removeInjectableConstructors'))
   .processor(require('./processors/processPackages'))
+  .processor(require('./processors/processNgModuleDocs'))
+
 
   /**
    * These are the API doc types that will be rendered to actual files.
@@ -41,7 +43,7 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
    * more Angular specific API types, such as decorators and directives.
    */
   .factory(function API_DOC_TYPES_TO_RENDER(EXPORT_DOC_TYPES) {
-    return EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe', 'package']);
+    return EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'ngmodule', 'pipe', 'package']);
   })
 
   /**
@@ -198,7 +200,7 @@ module.exports = new Package('angular-api', [basePackage, typeScriptPackage])
       outputPathTemplate: '${moduleFolder}.json'
     });
     computePathsProcessor.pathTemplates.push({
-      docTypes: EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe']),
+      docTypes: EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'ngmodule', 'pipe']),
       pathTemplate: '${moduleDoc.moduleFolder}/${name}',
       outputPathTemplate: '${moduleDoc.moduleFolder}/${name}.json',
     });

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

@@ -8,7 +8,7 @@ module.exports = function extractDecoratedClassesProcessor(EXPORT_DOC_TYPES) {
   return {
     $runAfter: ['processing-docs'],
     $runBefore: ['docs-processed'],
-    decoratorTypes: ['Directive', 'Component', 'Pipe'],
+    decoratorTypes: ['Directive', 'Component', 'Pipe', 'NgModule'],
     $process: function(docs) {
       var decoratorTypes = this.decoratorTypes;
 

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

@@ -0,0 +1,18 @@
+module.exports = function processNgModuleDocs() {
+  return {
+    $runAfter: ['extractDecoratedClassesProcessor'],
+    $runBefore: ['docs-processed'],
+    $process(docs) {
+      docs.forEach(doc => {
+        if (doc.docType === 'ngmodule') {
+          Object.keys(doc.ngmoduleOptions).forEach(key => {
+            const value = doc.ngmoduleOptions[key];
+            if (value && !Array.isArray(value)) {
+              doc.ngmoduleOptions[key] = [value];
+            }
+          });
+        }
+      });
+    }
+  };
+};

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

@@ -0,0 +1,24 @@
+const testPackage = require('../../helpers/test-package');
+const Dgeni = require('dgeni');
+
+describe('processNgModuleDocs processor', () => {
+  let processor;
+  beforeEach(() => {
+    const dgeni = new Dgeni([testPackage('angular-api-package')]);
+    const injector = dgeni.configureInjector();
+    processor = injector.get('processNgModuleDocs');
+  });
+
+  it('should be available on the injector', () => {
+    expect(processor.$process).toBeDefined();
+  });
+
+  it('should run before the correct processor', () => {
+    expect(processor.$runBefore).toEqual(['docs-processed']);
+  });
+
+  it('should run after the correct processor', () => {
+    expect(processor.$runAfter).toEqual(['extractDecoratedClassesProcessor']);
+  });
+
+});

aio/tools/transforms/templates/api/includes/class-overview.html

@@ -2,7 +2,7 @@
 
 <section class="{$ doc.docType $}-overview">
 <code-example language="ts" hideCopy="true" linenums="false">
-{% if doc.isAbstract %}abstract {% endif%}{$ doc.docType $} {$ doc.name $}{$ doc.typeParams | escape $}{$ memberHelper.renderHeritage(doc) $} {{$ memberHelper.renderMembers(doc) $}
+{% if doc.isAbstract %}abstract {% endif%}class {$ doc.name $}{$ doc.typeParams | escape $}{$ memberHelper.renderHeritage(doc) $} {{$ memberHelper.renderMembers(doc) $}
 }
 </code-example>
 {$ descendants.renderDescendants(doc, 'class', 'Subclasses') $}

aio/tools/transforms/templates/api/ngmodule.template.html

@@ -0,0 +1,54 @@
+{% import "lib/memberHelpers.html" as memberHelpers -%}
+{% import "lib/descendants.html" as descendants -%}
+{% import "lib/paramList.html" as params -%}
+{% extends 'export-base.template.html' -%}
+
+{% macro renderTable(items, containerClass, headingText, tableHeading) %}
+<section class="{$ containerClass $}">
+    <h2>{$ headingText $}</h2>
+    <table class="is-full-width list-table property-table">
+      <thead>
+        <tr>
+          <th>{$ tableHeading $}</th>
+        </tr>
+      </thead>
+      <tbody>
+      {% for item in items %}
+        <tr>
+          <td>
+            <code-example language="ts" hideCopy="true" linenums="false" class="no-box">
+              {$ item | escape $}
+            </code-example>
+          </td>
+        </tr>
+      {% endfor %}
+      </tbody>
+    </table>
+  </section>
+{% endmacro %}
+
+{% block overview %}
+  {% include "includes/class-overview.html" %}
+{% endblock %}
+{% block details %}
+  {% block additional %}{% endblock %}
+  {% include "includes/description.html" %}
+  {$ memberHelpers.renderProperties(doc.staticProperties, 'static-properties', 'static-property', 'Static properties') $}
+  {$ memberHelpers.renderMethodDetails(versionInfo, doc.staticMethods, 'static-methods', 'static-method', 'Static methods') $}
+  {% if doc.constructorDoc %}
+  <h2>Constructor</h2>
+  {$ memberHelpers.renderMethodDetail(versionInfo, doc.constructorDoc, 'constructor') $}{% endif %}
+
+  {$ memberHelpers.renderProperties(doc.properties, 'instance-properties', 'instance-property', 'Properties') $}
+
+  {$ memberHelpers.renderMethodDetails(versionInfo, doc.methods, 'instance-methods', 'instance-method', 'Methods') $}
+
+  {% if doc.ngmoduleOptions.providers %}
+  {$ renderTable(doc.ngmoduleOptions.providers, 'providers', 'Providers', 'Provider') $}
+  {% endif %}
+
+  {% if doc.ngmoduleOptions.exports %}
+  {$ renderTable(doc.ngmoduleOptions.exports, 'exports', 'Exports', 'Export') $}
+  {% endif %}
+
+{% endblock %}