From bc5cb8153e98e57b783b8734f3315e47baaf1c59 Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Wed, 29 Aug 2018 17:23:08 +0100 Subject: [PATCH] build(docs-infra): separate NgModules from Classes in API docs (#25734) PR Close #25734 --- .../custom-elements/api/api-list.component.ts | 1 + aio/src/styles/_constants.scss | 54 ++++++++++--------- .../transforms/angular-api-package/index.js | 6 ++- .../processors/extractDecoratedClasses.js | 2 +- .../processors/processNgModuleDocs.js | 18 +++++++ .../processors/processNgModuleDocs.spec.js | 24 +++++++++ .../api/includes/class-overview.html | 2 +- .../templates/api/ngmodule.template.html | 54 +++++++++++++++++++ 8 files changed, 132 insertions(+), 29 deletions(-) create mode 100644 aio/tools/transforms/angular-api-package/processors/processNgModuleDocs.js create mode 100644 aio/tools/transforms/angular-api-package/processors/processNgModuleDocs.spec.js create mode 100644 aio/tools/transforms/templates/api/ngmodule.template.html diff --git a/aio/src/app/custom-elements/api/api-list.component.ts b/aio/src/app/custom-elements/api/api-list.component.ts index 666b05aa49..4a8df37a5f 100644 --- a/aio/src/app/custom-elements/api/api-list.component.ts +++ b/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'} ]; diff --git a/aio/src/styles/_constants.scss b/aio/src/styles/_constants.scss index c719602f65..c7d30e4b70 100755 --- a/aio/src/styles/_constants.scss +++ b/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: ( - content: 'P', - background: $blue-grey-600 - ), - class: ( - content: 'C', - background: $blue-500 - ), - interface: ( - content: 'I', - background: $teal-500 + enum: ( + content: 'E', + background: $amber-700 ), function: ( content: 'F', background: $green-500 ), - enum: ( - content: 'E', - background: $amber-700 - ), - const: ( - content: 'K', - background: $mediumgray + interface: ( + content: 'I', + background: $teal-500 ), let: ( content: 'K', background: $mediumgray ), - var: ( - content: 'K', - background: $mediumgray + ngmodule: ( + content: 'M', + background: $darkred + ), + package: ( + content: 'Pk', + background: $purple-600 + ), + pipe: ( + content: 'P', + background: $blue-grey-600 ), type-alias: ( content: 'T', background: $light-green-600 ), - package: ( - content: 'Pk', - background: $purple-600 - ) + var: ( + content: 'K', + background: $mediumgray + ), ); // OTHER diff --git a/aio/tools/transforms/angular-api-package/index.js b/aio/tools/transforms/angular-api-package/index.js index a40e3f7ed1..9aeac8e8ce 100644 --- a/aio/tools/transforms/angular-api-package/index.js +++ b/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', }); diff --git a/aio/tools/transforms/angular-api-package/processors/extractDecoratedClasses.js b/aio/tools/transforms/angular-api-package/processors/extractDecoratedClasses.js index de643aa5a5..9224223721 100644 --- a/aio/tools/transforms/angular-api-package/processors/extractDecoratedClasses.js +++ b/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; diff --git a/aio/tools/transforms/angular-api-package/processors/processNgModuleDocs.js b/aio/tools/transforms/angular-api-package/processors/processNgModuleDocs.js new file mode 100644 index 0000000000..936bb9b5be --- /dev/null +++ b/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]; + } + }); + } + }); + } + }; +}; diff --git a/aio/tools/transforms/angular-api-package/processors/processNgModuleDocs.spec.js b/aio/tools/transforms/angular-api-package/processors/processNgModuleDocs.spec.js new file mode 100644 index 0000000000..49d1d20468 --- /dev/null +++ b/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']); + }); + +}); diff --git a/aio/tools/transforms/templates/api/includes/class-overview.html b/aio/tools/transforms/templates/api/includes/class-overview.html index d9064a17bf..c312d557c1 100644 --- a/aio/tools/transforms/templates/api/includes/class-overview.html +++ b/aio/tools/transforms/templates/api/includes/class-overview.html @@ -2,7 +2,7 @@
-{% 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) $} } {$ descendants.renderDescendants(doc, 'class', 'Subclasses') $} diff --git a/aio/tools/transforms/templates/api/ngmodule.template.html b/aio/tools/transforms/templates/api/ngmodule.template.html new file mode 100644 index 0000000000..b20f91d3b0 --- /dev/null +++ b/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) %} +
+

{$ headingText $}

+ + + + + + + + {% for item in items %} + + + + {% endfor %} + +
{$ tableHeading $}
+ + {$ item | escape $} + +
+
+{% 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 %} +

Constructor

+ {$ 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 %}