diff --git a/tools/dgeni/index.ts b/tools/dgeni/index.ts index 83b7a25de2c..2bd7d40750b 100644 --- a/tools/dgeni/index.ts +++ b/tools/dgeni/index.ts @@ -5,7 +5,7 @@ import {DocsPrivateFilter} from './processors/docs-private-filter'; import {Categorizer} from './processors/categorizer'; import {FilterDuplicateExports} from './processors/filter-duplicate-exports'; import {MergeInheritedProperties} from './processors/merge-inherited-properties'; -import {ComponentGrouper} from './processors/component-grouper'; +import {EntryPointGrouper} from './processors/entry-point-grouper'; import {ReadTypeScriptModules} from 'dgeni-packages/typescript/processors/readTypeScriptModules'; import {TsParser} from 'dgeni-packages/typescript/services/TsParser'; import {sync as globSync} from 'glob'; @@ -62,8 +62,8 @@ apiDocsPackage.processor(new DocsPrivateFilter()); // Processor that appends categorization flags to the docs, e.g. `isDirective`, `isNgModule`, etc. apiDocsPackage.processor(new Categorizer()); -// Processor to group components into top-level groups such as "Tabs", "Sidenav", etc. -apiDocsPackage.processor(new ComponentGrouper()); +// Processor to group docs into top-level entry-points such as "tabs", "sidenav", etc. +apiDocsPackage.processor(new EntryPointGrouper()); // Configure the log level of the API docs dgeni package. apiDocsPackage.config((log: any) => log.level = 'info'); @@ -82,7 +82,7 @@ apiDocsPackage.config((log: any) => patchLogService(log)); // Configure the output path for written files (i.e., file names). apiDocsPackage.config((computePathsProcessor: any) => { computePathsProcessor.pathTemplates = [{ - docTypes: ['componentGroup'], + docTypes: ['entry-point'], pathTemplate: '${name}', outputPathTemplate: '${name}.html', }]; diff --git a/tools/dgeni/processors/component-grouper.ts b/tools/dgeni/processors/entry-point-grouper.ts similarity index 53% rename from tools/dgeni/processors/component-grouper.ts rename to tools/dgeni/processors/entry-point-grouper.ts index e584b3906dd..68103d8590a 100644 --- a/tools/dgeni/processors/component-grouper.ts +++ b/tools/dgeni/processors/entry-point-grouper.ts @@ -1,23 +1,23 @@ import {DocCollection, Document, Processor} from 'dgeni'; +import {FunctionExportDoc} from 'dgeni-packages/typescript/api-doc-types/FunctionExportDoc'; import {InterfaceExportDoc} from 'dgeni-packages/typescript/api-doc-types/InterfaceExportDoc'; import {TypeAliasExportDoc} from 'dgeni-packages/typescript/api-doc-types/TypeAliasExportDoc'; -import {FunctionExportDoc} from 'dgeni-packages/typescript/api-doc-types/FunctionExportDoc'; -import {CategorizedClassDoc} from '../common/dgeni-definitions'; import * as path from 'path'; +import {CategorizedClassDoc} from '../common/dgeni-definitions'; -/** Component group data structure. */ -export class ComponentGroup { +/** Document type for an entry-point. */ +export class EntryPointDoc { /** Unique document type for Dgeni. */ - docType = 'componentGroup'; + docType = 'entry-point'; /** Name of the component group. */ name: string; - /** Display name of the component group */ + /** Display name of the entry-point. */ displayName: string; - /** Module import path for the component group. */ + /** Module import path for the entry-point. */ moduleImportPath: string; /** Name of the package, either material or cdk */ @@ -26,10 +26,10 @@ export class ComponentGroup { /** Display name of the package. */ packageDisplayName: string; - /** Unique id for the component group. */ + /** Unique id for the entry-point. */ id: string; - /** Known aliases for the component group. */ + /** Known aliases for the entry-point. This is only needed for the `computeIdsProcessor`. */ aliases: string[] = []; /** List of categorized class docs that are defining a directive. */ @@ -38,38 +38,37 @@ export class ComponentGroup { /** List of categorized class docs that are defining a service. */ services: CategorizedClassDoc[] = []; - /** Additional classes that belong to the component group. */ - additionalClasses: CategorizedClassDoc[] = []; + /** Classes that belong to the entry-point. */ + classes: CategorizedClassDoc[] = []; - /** Additional interfaces that belong to the component group. */ - additionalInterfaces: InterfaceExportDoc[] = []; + /** Interfaces that belong to the entry-point. */ + interfaces: InterfaceExportDoc[] = []; - /** Additional type aliases that belong to the component group. */ - additionalTypeAliases: TypeAliasExportDoc[] = []; + /** Type aliases that belong to the entry-point. */ + typeAliases: TypeAliasExportDoc[] = []; - /** Additional functions that belong to the component group. */ - additionalFunctions: FunctionExportDoc[] = []; + /** Functions that belong to the entry-point. */ + functions: FunctionExportDoc[] = []; - /** NgModule that defines the current component group. */ + /** NgModule that defines the current entry-point. */ ngModule: CategorizedClassDoc | null = null; constructor(name: string) { this.name = name; - this.id = `component-group-${name}`; + this.id = `entry-point-${name}`; } } /** - * Processor to group docs into top-level "Components" WRT material design, e.g., "Button", "Tabs", - * where each group may conists of several directives and services. + * Processor to group docs into entry-points that consist of directives, component, classes, + * interfaces, functions or type aliases. */ -export class ComponentGrouper implements Processor { - name = 'component-grouper'; +export class EntryPointGrouper implements Processor { + name = 'entry-point-grouper'; $runBefore = ['docs-processed']; $process(docs: DocCollection) { - // Map of group name to group instance. - const groups = new Map(); + const entryPoints = new Map(); docs.forEach(doc => { const documentInfo = getDocumentPackageInfo(doc); @@ -78,41 +77,41 @@ export class ComponentGrouper implements Processor { const packageDisplayName = documentInfo.packageName === 'cdk' ? 'CDK' : 'Material'; const moduleImportPath = `@angular/${packageName}/${documentInfo.entryPointName}`; - const groupName = packageName + '-' + documentInfo.name; + const entryPointName = packageName + '-' + documentInfo.name; - // Get the group for this doc, or, if one does not exist, create it. - let group; - if (groups.has(groupName)) { - group = groups.get(groupName)!; + // Get the entry-point for this doc, or, if one does not exist, create it. + let entryPoint; + if (entryPoints.has(entryPointName)) { + entryPoint = entryPoints.get(entryPointName)!; } else { - group = new ComponentGroup(groupName); - groups.set(groupName, group); + entryPoint = new EntryPointDoc(entryPointName); + entryPoints.set(entryPointName, entryPoint); } - group.displayName = documentInfo.name; - group.moduleImportPath = moduleImportPath; - group.packageName = packageName; - group.packageDisplayName = packageDisplayName; + entryPoint.displayName = documentInfo.name; + entryPoint.moduleImportPath = moduleImportPath; + entryPoint.packageName = packageName; + entryPoint.packageDisplayName = packageDisplayName; - // Put this doc into the appropriate list in this group. + // Put this doc into the appropriate list in the entry-point doc. if (doc.isDirective) { - group.directives.push(doc); + entryPoint.directives.push(doc); } else if (doc.isService) { - group.services.push(doc); + entryPoint.services.push(doc); } else if (doc.isNgModule) { - group.ngModule = doc; + entryPoint.ngModule = doc; } else if (doc.docType === 'class') { - group.additionalClasses.push(doc); + entryPoint.classes.push(doc); } else if (doc.docType === 'interface') { - group.additionalInterfaces.push(doc); + entryPoint.interfaces.push(doc); } else if (doc.docType === 'type-alias') { - group.additionalTypeAliases.push(doc); + entryPoint.typeAliases.push(doc); } else if (doc.docType === 'function') { - group.additionalFunctions.push(doc); + entryPoint.functions.push(doc); } }); - return Array.from(groups.values()); + return Array.from(entryPoints.values()); } } @@ -127,8 +126,9 @@ function getDocumentPackageInfo(doc: Document) { const pathSegments = path.relative(basePath, filePath).split(path.sep); let groupName = pathSegments[1]; - // For the ripples there should be a component group in the docs. Even it's not a - // secondary-entry point it can be still documented with its own `material-ripple.html` file. + // The ripples are technically part of the `@angular/material/core` entry-point, but we + // want to show the ripple API separately in the docs. In order to archive this, we treat + // the ripple folder as its own entry-point. if (pathSegments[1] === 'core' && pathSegments[2] === 'ripple') { groupName = 'ripple'; } diff --git a/tools/dgeni/templates/componentGroup.template.html b/tools/dgeni/templates/entry-point.template.html similarity index 65% rename from tools/dgeni/templates/componentGroup.template.html rename to tools/dgeni/templates/entry-point.template.html index 6eeefbec39b..d4bb70f1e35 100644 --- a/tools/dgeni/templates/componentGroup.template.html +++ b/tools/dgeni/templates/entry-point.template.html @@ -59,32 +59,32 @@ {% endfor %} {%- endif -%} - {%- if doc.additionalClasses.length -%} - - {% for other in doc.additionalClasses %} + {% for other in doc.classes %} {$ class(other) $} {% endfor %} {%- endif -%} - {%- if doc.additionalInterfaces.length -%} - - {% for item in doc.additionalInterfaces %} + {% for item in doc.interfaces %} {$ interface(item) $} {% endfor %} {%- endif -%} - {%- if doc.additionalFunctions.length -%} - - {% for item in doc.additionalFunctions %} + {% for item in doc.functions %} {# Since the function docs have a similar structure as method docs, we use the method template. @@ -93,12 +93,12 @@ {% endfor %} {%- endif -%} - {%- if doc.additionalTypeAliases.length -%} - - {% for item in doc.additionalTypeAliases %} + {% for item in doc.typeAliases %} {$ typeAlias(item) $} {% endfor %} {%- endif -%}