From 9ccda9465b7c3ba6514e7f418a1c07214faa28ed Mon Sep 17 00:00:00 2001 From: Paul Gschwendtner Date: Tue, 27 Nov 2018 22:04:43 +0100 Subject: [PATCH] build: allow jumping to base class of api class (#14232) References #14122 --- test/karma-test-shim.js | 2 - tools/dgeni/common/compute-api-url.ts | 14 +++++++ tools/dgeni/index.ts | 5 +++ tools/dgeni/processors/entry-point-grouper.ts | 41 +++++++++++++------ tools/dgeni/templates/class.template.html | 4 +- 5 files changed, 51 insertions(+), 15 deletions(-) create mode 100644 tools/dgeni/common/compute-api-url.ts diff --git a/test/karma-test-shim.js b/test/karma-test-shim.js index 8d7d6490cd4..f2406abd5d2 100644 --- a/test/karma-test-shim.js +++ b/test/karma-test-shim.js @@ -46,9 +46,7 @@ function configureTestBed() { var testing = providers[1]; var testingBrowser = providers[2]; - console.log('----------'); console.log('Running tests using Angular version: ' + core.VERSION.full); - console.log('----------'); var testBed = testing.TestBed.initTestEnvironment( testingBrowser.BrowserDynamicTestingModule, diff --git a/tools/dgeni/common/compute-api-url.ts b/tools/dgeni/common/compute-api-url.ts new file mode 100644 index 00000000000..9ac5100f719 --- /dev/null +++ b/tools/dgeni/common/compute-api-url.ts @@ -0,0 +1,14 @@ +import {Document} from 'dgeni'; +import {ModuleInfo} from '../processors/entry-point-grouper'; + +/** + * Computes an URL that refers to the given API document in the docs. Note that this logic + * needs to be kept in sync with the routes from the material.angular.io CLI project. + */ +export function computeApiDocumentUrl(apiDoc: Document, moduleInfo: ModuleInfo): string { + // Base URL for the given package. This is currently either: + // 1) material.angular.io/cdk + // 2) material.angular.io/components + const baseUrl = moduleInfo.packageName === 'cdk' ? 'cdk' : 'components'; + return `${baseUrl}/${moduleInfo.entryPointName}/api#${apiDoc.name}`; +} diff --git a/tools/dgeni/index.ts b/tools/dgeni/index.ts index d0518fe15da..195203457a2 100644 --- a/tools/dgeni/index.ts +++ b/tools/dgeni/index.ts @@ -98,6 +98,11 @@ apiDocsPackage.config((parseTagsProcessor: any) => { ]); }); +apiDocsPackage.config((checkAnchorLinksProcessor: any) => { + // This ensures that Dgeni will fail if we generate links that don't follow this format. + checkAnchorLinksProcessor.ignoredLinks.push(/(components|cdk)\/[\w-]+\/api#\w+/); +}); + // Configure the processor for understanding TypeScript. apiDocsPackage.config((readTypeScriptModules: ReadTypeScriptModules, tsParser: TsParser) => { readTypeScriptModules.basePath = sourceDir; diff --git a/tools/dgeni/processors/entry-point-grouper.ts b/tools/dgeni/processors/entry-point-grouper.ts index 4d2aec6a86c..5fd294304e3 100644 --- a/tools/dgeni/processors/entry-point-grouper.ts +++ b/tools/dgeni/processors/entry-point-grouper.ts @@ -4,8 +4,18 @@ import {FunctionExportDoc} from 'dgeni-packages/typescript/api-doc-types/Functio import {InterfaceExportDoc} from 'dgeni-packages/typescript/api-doc-types/InterfaceExportDoc'; import {TypeAliasExportDoc} from 'dgeni-packages/typescript/api-doc-types/TypeAliasExportDoc'; import * as path from 'path'; +import {computeApiDocumentUrl} from '../common/compute-api-url'; import {CategorizedClassDoc} from '../common/dgeni-definitions'; +export interface ModuleInfo { + /** Name of the module (e.g. toolbar, drag-drop, ripple) */ + name: string; + /** Name of the package that contains this entry point. */ + packageName: string; + /** Name of the entry-point that contains this module. */ + entryPointName: string; +} + /** Document type for an entry-point. */ export class EntryPointDoc { @@ -75,13 +85,17 @@ export class EntryPointGrouper implements Processor { const entryPoints = new Map(); docs.forEach(doc => { - const documentInfo = getDocumentPackageInfo(doc); + const moduleInfo = getModulePackageInfo(doc); - const packageName = documentInfo.packageName; - const packageDisplayName = documentInfo.packageName === 'cdk' ? 'CDK' : 'Material'; + const packageName = moduleInfo.packageName; + const packageDisplayName = packageName === 'cdk' ? 'CDK' : 'Material'; - const moduleImportPath = `@angular/${packageName}/${documentInfo.entryPointName}`; - const entryPointName = packageName + '-' + documentInfo.name; + const moduleImportPath = `@angular/${packageName}/${moduleInfo.entryPointName}`; + const entryPointName = packageName + '-' + moduleInfo.name; + + // Compute a public URL that refers to the document. This is helpful if we want to + // make references to other API documents. e.g. showing the extended class. + doc.publicUrl = computeApiDocumentUrl(doc, moduleInfo); // Get the entry-point for this doc, or, if one does not exist, create it. let entryPoint; @@ -92,7 +106,7 @@ export class EntryPointGrouper implements Processor { entryPoints.set(entryPointName, entryPoint); } - entryPoint.displayName = documentInfo.name; + entryPoint.displayName = moduleInfo.name; entryPoint.moduleImportPath = moduleImportPath; entryPoint.packageName = packageName; entryPoint.packageDisplayName = packageDisplayName; @@ -121,8 +135,8 @@ export class EntryPointGrouper implements Processor { } } -/** Resolves package information for the given Dgeni document. */ -function getDocumentPackageInfo(doc: Document) { +/** Resolves module package information of the given Dgeni document. */ +function getModulePackageInfo(doc: Document): ModuleInfo { // Full path to the file for this doc. const basePath = doc.fileInfo.basePath; const filePath = doc.fileInfo.filePath; @@ -130,17 +144,20 @@ function getDocumentPackageInfo(doc: Document) { // All of the component documentation is under either `src/lib` or `src/cdk`. // We group the docs up by the directory immediately under that root. const pathSegments = path.relative(basePath, filePath).split(path.sep); - let groupName = pathSegments[1]; + + // The module name is usually the entry-point (e.g. slide-toggle, toolbar), but this is not + // guaranteed because we can also export a module from lib/core. e.g. the ripple module. + let moduleName = pathSegments[1]; // 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. + // the ripple folder as its own module. if (pathSegments[1] === 'core' && pathSegments[2] === 'ripple') { - groupName = 'ripple'; + moduleName = 'ripple'; } return { - name: groupName, + name: moduleName, packageName: pathSegments[0] === 'lib' ? 'material' : pathSegments[0], entryPointName: pathSegments[1], }; diff --git a/tools/dgeni/templates/class.template.html b/tools/dgeni/templates/class.template.html index 36a53556364..68538ebcbdd 100644 --- a/tools/dgeni/templates/class.template.html +++ b/tools/dgeni/templates/class.template.html @@ -6,7 +6,9 @@ {% if class.extendedDoc %} extends - {$ class.extendedDoc.name $} + + {$ class.extendedDoc.name $} + {% endif %}