diff --git a/aio/tools/transforms/angular-api-package/index.js b/aio/tools/transforms/angular-api-package/index.js new file mode 100644 index 0000000000..252c60d370 --- /dev/null +++ b/aio/tools/transforms/angular-api-package/index.js @@ -0,0 +1,118 @@ +/** + * @license + * Copyright Google Inc. All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.io/license + */ +const Package = require('dgeni').Package; + +const basePackage = require('../angular-base-package'); +const typeScriptPackage = require('dgeni-packages/typescript'); +const { API_SOURCE_PATH, requireFolder } = require('../config'); + +module.exports = new Package('angular-api', [basePackage, typeScriptPackage]) + + // Register the processors + .processor(require('./processors/convertPrivateClassesToInterfaces')) + .processor(require('./processors/generateApiListDoc')) + .processor(require('./processors/addNotYetDocumentedProperty')) + .processor(require('./processors/mergeDecoratorDocs')) + .processor(require('./processors/extractDecoratedClasses')) + .processor(require('./processors/matchUpDirectiveDecorators')) + .processor(require('./processors/filterMemberDocs')) + .processor(require('./processors/markBarredODocsAsPrivate')) + .processor(require('./processors/filterPrivateDocs')) + .processor(require('./processors/filterIgnoredDocs')) + + // Where do we get the source files? + .config(function(readTypeScriptModules, readFilesProcessor, collectExamples) { + + // API files are typescript + readTypeScriptModules.basePath = API_SOURCE_PATH; + readTypeScriptModules.ignoreExportsMatching = [/^[_ɵ]/]; + readTypeScriptModules.hidePrivateMembers = true; + readTypeScriptModules.sourceFiles = [ + 'common/index.ts', + 'common/testing/index.ts', + 'core/index.ts', + 'core/testing/index.ts', + 'forms/index.ts', + 'http/index.ts', + 'http/testing/index.ts', + 'platform-browser/index.ts', + 'platform-browser/testing/index.ts', + 'platform-browser-dynamic/index.ts', + 'platform-browser-dynamic/testing/index.ts', + 'platform-server/index.ts', + 'platform-server/testing/index.ts', + 'platform-webworker/index.ts', + 'platform-webworker-dynamic/index.ts', + 'router/index.ts', + 'router/testing/index.ts', + 'upgrade/index.ts', + 'upgrade/static.ts', + ]; + + // API Examples + readFilesProcessor.sourceFiles = [ + { + basePath: API_SOURCE_PATH, + include: API_SOURCE_PATH + '/examples/**/*', + fileReader: 'exampleFileReader' + } + ]; + collectExamples.exampleFolders.push('examples'); + }) + + // Ignore certain problematic files + .config(function(filterIgnoredDocs) { + filterIgnoredDocs.ignore = [ + /\/VERSION$/ // Ignore the `VERSION` const, since it would be written to the same file as the `Version` class + ]; + }) + + // Configure jsdoc-style tag parsing + .config(function(parseTagsProcessor, getInjectables) { + // 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 = []; + } + }); + }) + + + .config(function(computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc) { + + const API_SEGMENT = 'api'; + + generateApiListDoc.outputFolder = API_SEGMENT; + + computePathsProcessor.pathTemplates.push({ + docTypes: ['module'], + getPath: function computeModulePath(doc) { + doc.moduleFolder = `${API_SEGMENT}/${doc.id.replace(/\/index$/, '')}`; + return doc.moduleFolder; + }, + outputPathTemplate: '${moduleFolder}.json' + }); + computePathsProcessor.pathTemplates.push({ + docTypes: EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe']), + pathTemplate: '${moduleDoc.moduleFolder}/${name}', + outputPathTemplate: '${moduleDoc.moduleFolder}/${name}.json', + }); + }) + + .config(function(convertToJsonProcessor, EXPORT_DOC_TYPES) { + const DOCS_TO_CONVERT = EXPORT_DOC_TYPES.concat([ + 'decorator', 'directive', 'pipe', 'module' + ]); + convertToJsonProcessor.docTypes = convertToJsonProcessor.docTypes.concat(DOCS_TO_CONVERT); + }); diff --git a/aio/tools/transforms/angular.io-package/mocks/importedSrc.ts b/aio/tools/transforms/angular-api-package/mocks/importedSrc.ts similarity index 100% rename from aio/tools/transforms/angular.io-package/mocks/importedSrc.ts rename to aio/tools/transforms/angular-api-package/mocks/importedSrc.ts diff --git a/aio/tools/transforms/angular.io-package/mocks/testSrc.ts b/aio/tools/transforms/angular-api-package/mocks/testSrc.ts similarity index 100% rename from aio/tools/transforms/angular.io-package/mocks/testSrc.ts rename to aio/tools/transforms/angular-api-package/mocks/testSrc.ts diff --git a/aio/tools/transforms/angular.io-package/processors/addNotYetDocumentedProperty.js b/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/addNotYetDocumentedProperty.js rename to aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.js diff --git a/aio/tools/transforms/angular.io-package/processors/addNotYetDocumentedProperty.spec.js b/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.spec.js similarity index 98% rename from aio/tools/transforms/angular.io-package/processors/addNotYetDocumentedProperty.spec.js rename to aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.spec.js index ab71e43227..f277bca79b 100644 --- a/aio/tools/transforms/angular.io-package/processors/addNotYetDocumentedProperty.spec.js +++ b/aio/tools/transforms/angular-api-package/processors/addNotYetDocumentedProperty.spec.js @@ -5,7 +5,7 @@ describe('addNotYetDocumentedProperty', function() { var dgeni, injector, processor; beforeEach(function() { - dgeni = new Dgeni([testPackage('angular.io-package')]); + dgeni = new Dgeni([testPackage('angular-api-package')]); injector = dgeni.configureInjector(); processor = injector.get('addNotYetDocumentedProperty'); }); diff --git a/aio/tools/transforms/angular.io-package/processors/convertPrivateClassesToInterfaces.js b/aio/tools/transforms/angular-api-package/processors/convertPrivateClassesToInterfaces.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/convertPrivateClassesToInterfaces.js rename to aio/tools/transforms/angular-api-package/processors/convertPrivateClassesToInterfaces.js diff --git a/aio/tools/transforms/angular.io-package/processors/extractDecoratedClasses.js b/aio/tools/transforms/angular-api-package/processors/extractDecoratedClasses.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/extractDecoratedClasses.js rename to aio/tools/transforms/angular-api-package/processors/extractDecoratedClasses.js diff --git a/aio/tools/transforms/angular.io-package/processors/extractDecoratedClasses.spec.js b/aio/tools/transforms/angular-api-package/processors/extractDecoratedClasses.spec.js similarity index 95% rename from aio/tools/transforms/angular.io-package/processors/extractDecoratedClasses.spec.js rename to aio/tools/transforms/angular-api-package/processors/extractDecoratedClasses.spec.js index a323945017..b626f6c130 100644 --- a/aio/tools/transforms/angular.io-package/processors/extractDecoratedClasses.spec.js +++ b/aio/tools/transforms/angular-api-package/processors/extractDecoratedClasses.spec.js @@ -5,7 +5,7 @@ describe('extractDecoratedClasses processor', function() { var dgeni, injector, processor; beforeEach(function() { - dgeni = new Dgeni([testPackage('angular.io-package')]); + dgeni = new Dgeni([testPackage('angular-api-package')]); injector = dgeni.configureInjector(); processor = injector.get('extractDecoratedClassesProcessor'); }); diff --git a/aio/tools/transforms/angular.io-package/processors/filterIgnoredDocs.js b/aio/tools/transforms/angular-api-package/processors/filterIgnoredDocs.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/filterIgnoredDocs.js rename to aio/tools/transforms/angular-api-package/processors/filterIgnoredDocs.js diff --git a/aio/tools/transforms/angular.io-package/processors/filterIgnoredDocs.spec.js b/aio/tools/transforms/angular-api-package/processors/filterIgnoredDocs.spec.js similarity index 94% rename from aio/tools/transforms/angular.io-package/processors/filterIgnoredDocs.spec.js rename to aio/tools/transforms/angular-api-package/processors/filterIgnoredDocs.spec.js index a44a16220b..c47c6b1966 100644 --- a/aio/tools/transforms/angular.io-package/processors/filterIgnoredDocs.spec.js +++ b/aio/tools/transforms/angular-api-package/processors/filterIgnoredDocs.spec.js @@ -5,7 +5,7 @@ const Dgeni = require('dgeni'); describe('filterIgnoredDocs processor', () => { it('should be available on the injector', () => { - const dgeni = new Dgeni([testPackage('angular.io-package')]); + const dgeni = new Dgeni([testPackage('angular-api-package')]); const injector = dgeni.configureInjector(); const processor = injector.get('filterIgnoredDocs'); expect(processor.$process).toBeDefined(); diff --git a/aio/tools/transforms/angular.io-package/processors/filterMemberDocs.js b/aio/tools/transforms/angular-api-package/processors/filterMemberDocs.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/filterMemberDocs.js rename to aio/tools/transforms/angular-api-package/processors/filterMemberDocs.js diff --git a/aio/tools/transforms/angular.io-package/processors/filterPrivateDocs.js b/aio/tools/transforms/angular-api-package/processors/filterPrivateDocs.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/filterPrivateDocs.js rename to aio/tools/transforms/angular-api-package/processors/filterPrivateDocs.js diff --git a/aio/tools/transforms/angular.io-package/processors/filterPrivateDocs.spec.js b/aio/tools/transforms/angular-api-package/processors/filterPrivateDocs.spec.js similarity index 94% rename from aio/tools/transforms/angular.io-package/processors/filterPrivateDocs.spec.js rename to aio/tools/transforms/angular-api-package/processors/filterPrivateDocs.spec.js index 1301118ed6..3f9831e4b5 100644 --- a/aio/tools/transforms/angular.io-package/processors/filterPrivateDocs.spec.js +++ b/aio/tools/transforms/angular-api-package/processors/filterPrivateDocs.spec.js @@ -5,7 +5,7 @@ const Dgeni = require('dgeni'); describe('filterPrivateDocs processor', () => { it('should be available on the injector', () => { - const dgeni = new Dgeni([testPackage('angular.io-package')]); + const dgeni = new Dgeni([testPackage('angular-api-package')]); const injector = dgeni.configureInjector(); const processor = injector.get('filterPrivateDocs'); expect(processor.$process).toBeDefined(); diff --git a/aio/tools/transforms/angular.io-package/processors/generateApiListDoc.js b/aio/tools/transforms/angular-api-package/processors/generateApiListDoc.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/generateApiListDoc.js rename to aio/tools/transforms/angular-api-package/processors/generateApiListDoc.js diff --git a/aio/tools/transforms/angular.io-package/processors/generateApiListDoc.spec.js b/aio/tools/transforms/angular-api-package/processors/generateApiListDoc.spec.js similarity index 99% rename from aio/tools/transforms/angular.io-package/processors/generateApiListDoc.spec.js rename to aio/tools/transforms/angular-api-package/processors/generateApiListDoc.spec.js index 83f79df765..1eb09830ca 100644 --- a/aio/tools/transforms/angular.io-package/processors/generateApiListDoc.spec.js +++ b/aio/tools/transforms/angular-api-package/processors/generateApiListDoc.spec.js @@ -5,7 +5,7 @@ const Dgeni = require('dgeni'); describe('generateApiListDoc processor', () => { it('should be available on the injector', () => { - const dgeni = new Dgeni([testPackage('angular.io-package')]); + const dgeni = new Dgeni([testPackage('angular-api-package')]); const injector = dgeni.configureInjector(); const processor = injector.get('generateApiListDoc'); expect(processor.$process).toBeDefined(); diff --git a/aio/tools/transforms/angular.io-package/processors/markBarredODocsAsPrivate.js b/aio/tools/transforms/angular-api-package/processors/markBarredODocsAsPrivate.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/markBarredODocsAsPrivate.js rename to aio/tools/transforms/angular-api-package/processors/markBarredODocsAsPrivate.js diff --git a/aio/tools/transforms/angular.io-package/processors/markBarredODocsAsPrivate.spec.js b/aio/tools/transforms/angular-api-package/processors/markBarredODocsAsPrivate.spec.js similarity index 92% rename from aio/tools/transforms/angular.io-package/processors/markBarredODocsAsPrivate.spec.js rename to aio/tools/transforms/angular-api-package/processors/markBarredODocsAsPrivate.spec.js index 48151df634..a46e7e36f0 100644 --- a/aio/tools/transforms/angular.io-package/processors/markBarredODocsAsPrivate.spec.js +++ b/aio/tools/transforms/angular-api-package/processors/markBarredODocsAsPrivate.spec.js @@ -5,7 +5,7 @@ const Dgeni = require('dgeni'); describe('generateApiListDoc processor', () => { it('should be available on the injector', () => { - const dgeni = new Dgeni([testPackage('angular.io-package')]); + const dgeni = new Dgeni([testPackage('angular-api-package')]); const injector = dgeni.configureInjector(); const processor = injector.get('markBarredODocsAsPrivate'); expect(processor.$process).toBeDefined(); diff --git a/aio/tools/transforms/angular.io-package/processors/matchUpDirectiveDecorators.js b/aio/tools/transforms/angular-api-package/processors/matchUpDirectiveDecorators.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/matchUpDirectiveDecorators.js rename to aio/tools/transforms/angular-api-package/processors/matchUpDirectiveDecorators.js diff --git a/aio/tools/transforms/angular.io-package/processors/mergeDecoratorDocs.js b/aio/tools/transforms/angular-api-package/processors/mergeDecoratorDocs.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/mergeDecoratorDocs.js rename to aio/tools/transforms/angular-api-package/processors/mergeDecoratorDocs.js diff --git a/aio/tools/transforms/angular.io-package/processors/mergeDecoratorDocs.spec.js b/aio/tools/transforms/angular-api-package/processors/mergeDecoratorDocs.spec.js similarity index 96% rename from aio/tools/transforms/angular.io-package/processors/mergeDecoratorDocs.spec.js rename to aio/tools/transforms/angular-api-package/processors/mergeDecoratorDocs.spec.js index 67c456e7d5..6024978c18 100644 --- a/aio/tools/transforms/angular.io-package/processors/mergeDecoratorDocs.spec.js +++ b/aio/tools/transforms/angular-api-package/processors/mergeDecoratorDocs.spec.js @@ -5,7 +5,7 @@ describe('mergeDecoratorDocs processor', function() { var dgeni, injector, processor, decoratorDoc, decoratorDocWithTypeAssertion, otherDoc; beforeEach(function() { - dgeni = new Dgeni([testPackage('angular.io-package')]); + dgeni = new Dgeni([testPackage('angular-api-package')]); injector = dgeni.configureInjector(); processor = injector.get('mergeDecoratorDocs'); diff --git a/aio/tools/transforms/angular.io-package/tag-defs/Annotation.js b/aio/tools/transforms/angular-api-package/tag-defs/Annotation.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/Annotation.js rename to aio/tools/transforms/angular-api-package/tag-defs/Annotation.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/deprecated.js b/aio/tools/transforms/angular-api-package/tag-defs/deprecated.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/deprecated.js rename to aio/tools/transforms/angular-api-package/tag-defs/deprecated.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/docsNotRequired.js b/aio/tools/transforms/angular-api-package/tag-defs/docsNotRequired.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/docsNotRequired.js rename to aio/tools/transforms/angular-api-package/tag-defs/docsNotRequired.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/experimental.js b/aio/tools/transforms/angular-api-package/tag-defs/experimental.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/experimental.js rename to aio/tools/transforms/angular-api-package/tag-defs/experimental.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/howToUse.js b/aio/tools/transforms/angular-api-package/tag-defs/howToUse.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/howToUse.js rename to aio/tools/transforms/angular-api-package/tag-defs/howToUse.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/internal.js b/aio/tools/transforms/angular-api-package/tag-defs/internal.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/internal.js rename to aio/tools/transforms/angular-api-package/tag-defs/internal.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/ngModule.js b/aio/tools/transforms/angular-api-package/tag-defs/ngModule.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/ngModule.js rename to aio/tools/transforms/angular-api-package/tag-defs/ngModule.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/no-description.js b/aio/tools/transforms/angular-api-package/tag-defs/no-description.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/no-description.js rename to aio/tools/transforms/angular-api-package/tag-defs/no-description.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/security.js b/aio/tools/transforms/angular-api-package/tag-defs/security.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/security.js rename to aio/tools/transforms/angular-api-package/tag-defs/security.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/stable.js b/aio/tools/transforms/angular-api-package/tag-defs/stable.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/stable.js rename to aio/tools/transforms/angular-api-package/tag-defs/stable.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/suppress.js b/aio/tools/transforms/angular-api-package/tag-defs/suppress.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/suppress.js rename to aio/tools/transforms/angular-api-package/tag-defs/suppress.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/syntax.js b/aio/tools/transforms/angular-api-package/tag-defs/syntax.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/syntax.js rename to aio/tools/transforms/angular-api-package/tag-defs/syntax.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/ts2dart_const.js b/aio/tools/transforms/angular-api-package/tag-defs/ts2dart_const.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/ts2dart_const.js rename to aio/tools/transforms/angular-api-package/tag-defs/ts2dart_const.js diff --git a/aio/tools/transforms/angular.io-package/tag-defs/whatItDoes.js b/aio/tools/transforms/angular-api-package/tag-defs/whatItDoes.js similarity index 100% rename from aio/tools/transforms/angular.io-package/tag-defs/whatItDoes.js rename to aio/tools/transforms/angular-api-package/tag-defs/whatItDoes.js diff --git a/aio/tools/transforms/angular.io-package/ignore.words b/aio/tools/transforms/angular-base-package/ignore.words similarity index 100% rename from aio/tools/transforms/angular.io-package/ignore.words rename to aio/tools/transforms/angular-base-package/ignore.words diff --git a/aio/tools/transforms/angular-base-package/index.js b/aio/tools/transforms/angular-base-package/index.js new file mode 100644 index 0000000000..4b50e5f81c --- /dev/null +++ b/aio/tools/transforms/angular-base-package/index.js @@ -0,0 +1,116 @@ +/** + * @license + * Copyright Google Inc. All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.io/license + */ +const path = require('path'); +const Package = require('dgeni').Package; + +const jsdocPackage = require('dgeni-packages/jsdoc'); +const nunjucksPackage = require('dgeni-packages/nunjucks'); +const linksPackage = require('../links-package'); +const examplesPackage = require('../examples-package'); +const targetPackage = require('../target-package'); +const remarkPackage = require('../remark-package'); + +const { PROJECT_ROOT, DOCS_OUTPUT_PATH, TEMPLATES_PATH, requireFolder } = require('../config'); + +module.exports = new Package('angular-base', [ + jsdocPackage, nunjucksPackage, linksPackage, examplesPackage, targetPackage, remarkPackage +]) + + // Register the processors + .processor(require('./processors/generateKeywords')) + .processor(require('./processors/createOverviewDump')) + .processor(require('./processors/checkUnbalancedBackTicks')) + .processor(require('./processors/convertToJson')) + .processor(require('./processors/fixInternalDocumentLinks')) + + // overrides base packageInfo and returns the one for the 'angular/angular' repo. + .factory('packageInfo', function() { return require(path.resolve(PROJECT_ROOT, 'package.json')); }) + .factory(require('./readers/json')) + + .config(function(checkAnchorLinksProcessor) { + // TODO: re-enable + checkAnchorLinksProcessor.$enabled = false; + }) + + // Where do we get the source files? + .config(function(readFilesProcessor, collectExamples, generateKeywordsProcessor, jsonFileReader) { + + readFilesProcessor.fileReaders.push(jsonFileReader); + readFilesProcessor.basePath = PROJECT_ROOT; + readFilesProcessor.sourceFiles = []; + collectExamples.exampleFolders = []; + + generateKeywordsProcessor.ignoreWordsFile = path.resolve(__dirname, 'ignore.words'); + generateKeywordsProcessor.docTypesToIgnore = ['example-region']; + }) + + // Where do we write the output files? + .config(function(writeFilesProcessor) { writeFilesProcessor.outputFolder = DOCS_OUTPUT_PATH; }) + + + // Target environments + .config(function(targetEnvironments) { + const ALLOWED_LANGUAGES = ['ts', 'js', 'dart']; + const TARGET_LANGUAGE = 'ts'; + + ALLOWED_LANGUAGES.forEach(target => targetEnvironments.addAllowed(target)); + targetEnvironments.activate(TARGET_LANGUAGE); + }) + + + // Configure nunjucks rendering of docs via templates + .config(function( + renderDocsProcessor, templateFinder, templateEngine, getInjectables) { + + // Where to find the templates for the doc rendering + templateFinder.templateFolders = [TEMPLATES_PATH]; + + // Standard patterns for matching docs to templates + templateFinder.templatePatterns = [ + '${ doc.template }', '${ doc.id }.${ doc.docType }.template.html', + '${ doc.id }.template.html', '${ doc.docType }.template.html', + '${ doc.id }.${ doc.docType }.template.js', '${ doc.id }.template.js', + '${ doc.docType }.template.js', '${ doc.id }.${ doc.docType }.template.json', + '${ doc.id }.template.json', '${ doc.docType }.template.json', 'common.template.html' + ]; + + // Nunjucks and Angular conflict in their template bindings so change Nunjucks + templateEngine.config.tags = {variableStart: '{$', variableEnd: '$}'}; + + templateEngine.filters = + templateEngine.filters.concat(getInjectables(requireFolder(__dirname, './rendering'))); + + // helpers are made available to the nunjucks templates + renderDocsProcessor.helpers.relativePath = function(from, to) { + return path.relative(from, to); + }; + }) + + + + // We are not going to be relaxed about ambiguous links + .config(function(getLinkInfo) { + getLinkInfo.useFirstAmbiguousLink = false; + }) + + + + .config(function(computePathsProcessor, generateKeywordsProcessor) { + + generateKeywordsProcessor.outputFolder = 'app'; + + // Replace any path templates inherited from other packages + // (we want full and transparent control) + computePathsProcessor.pathTemplates = [ + {docTypes: ['example-region'], getOutputPath: function() {}}, + ]; + }) + + .config(function(convertToJsonProcessor) { + convertToJsonProcessor.docTypes = []; + }); diff --git a/aio/tools/transforms/angular.io-package/processors/checkUnbalancedBackTicks.js b/aio/tools/transforms/angular-base-package/processors/checkUnbalancedBackTicks.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/checkUnbalancedBackTicks.js rename to aio/tools/transforms/angular-base-package/processors/checkUnbalancedBackTicks.js diff --git a/aio/tools/transforms/angular.io-package/processors/checkUnbalancedBackTicks.spec.js b/aio/tools/transforms/angular-base-package/processors/checkUnbalancedBackTicks.spec.js similarity index 93% rename from aio/tools/transforms/angular.io-package/processors/checkUnbalancedBackTicks.spec.js rename to aio/tools/transforms/angular-base-package/processors/checkUnbalancedBackTicks.spec.js index bc9cd4c6fb..7b5a718389 100644 --- a/aio/tools/transforms/angular.io-package/processors/checkUnbalancedBackTicks.spec.js +++ b/aio/tools/transforms/angular-base-package/processors/checkUnbalancedBackTicks.spec.js @@ -5,7 +5,7 @@ describe('checkUnbalancedBackTicks', function() { var dgeni, injector, processor, log; beforeEach(function() { - dgeni = new Dgeni([testPackage('angular.io-package')]); + dgeni = new Dgeni([testPackage('angular-base-package')]); injector = dgeni.configureInjector(); processor = injector.get('checkUnbalancedBackTicks'); log = injector.get('log'); diff --git a/aio/tools/transforms/angular.io-package/processors/convertToJson.js b/aio/tools/transforms/angular-base-package/processors/convertToJson.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/convertToJson.js rename to aio/tools/transforms/angular-base-package/processors/convertToJson.js diff --git a/aio/tools/transforms/angular.io-package/processors/convertToJson.spec.js b/aio/tools/transforms/angular-base-package/processors/convertToJson.spec.js similarity index 97% rename from aio/tools/transforms/angular.io-package/processors/convertToJson.spec.js rename to aio/tools/transforms/angular-base-package/processors/convertToJson.spec.js index 8f336b983c..043267ae10 100644 --- a/aio/tools/transforms/angular.io-package/processors/convertToJson.spec.js +++ b/aio/tools/transforms/angular-base-package/processors/convertToJson.spec.js @@ -5,7 +5,7 @@ describe('convertToJson processor', () => { var dgeni, injector, processor, log; beforeAll(function() { - dgeni = new Dgeni([testPackage('angular.io-package')]); + dgeni = new Dgeni([testPackage('angular-base-package')]); injector = dgeni.configureInjector(); processor = injector.get('convertToJsonProcessor'); log = injector.get('log'); diff --git a/aio/tools/transforms/angular.io-package/processors/createOverviewDump.js b/aio/tools/transforms/angular-base-package/processors/createOverviewDump.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/createOverviewDump.js rename to aio/tools/transforms/angular-base-package/processors/createOverviewDump.js diff --git a/aio/tools/transforms/angular.io-package/processors/fixInternalDocumentLinks.js b/aio/tools/transforms/angular-base-package/processors/fixInternalDocumentLinks.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/fixInternalDocumentLinks.js rename to aio/tools/transforms/angular-base-package/processors/fixInternalDocumentLinks.js diff --git a/aio/tools/transforms/angular.io-package/processors/fixInternalDocumentLinks.spec.js b/aio/tools/transforms/angular-base-package/processors/fixInternalDocumentLinks.spec.js similarity index 96% rename from aio/tools/transforms/angular.io-package/processors/fixInternalDocumentLinks.spec.js rename to aio/tools/transforms/angular-base-package/processors/fixInternalDocumentLinks.spec.js index 138198ce41..d8957ec997 100644 --- a/aio/tools/transforms/angular.io-package/processors/fixInternalDocumentLinks.spec.js +++ b/aio/tools/transforms/angular-base-package/processors/fixInternalDocumentLinks.spec.js @@ -5,7 +5,7 @@ const Dgeni = require('dgeni'); describe('fixInternalDocumentLinks processor', () => { it('should be available on the injector', () => { - const dgeni = new Dgeni([testPackage('angular.io-package')]); + const dgeni = new Dgeni([testPackage('angular-base-package')]); const injector = dgeni.configureInjector(); const processor = injector.get('fixInternalDocumentLinks'); expect(processor.$process).toBeDefined(); diff --git a/aio/tools/transforms/angular.io-package/processors/generateKeywords.js b/aio/tools/transforms/angular-base-package/processors/generateKeywords.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/generateKeywords.js rename to aio/tools/transforms/angular-base-package/processors/generateKeywords.js diff --git a/aio/tools/transforms/angular.io-package/processors/generateKeywords.spec.js b/aio/tools/transforms/angular-base-package/processors/generateKeywords.spec.js similarity index 95% rename from aio/tools/transforms/angular.io-package/processors/generateKeywords.spec.js rename to aio/tools/transforms/angular-base-package/processors/generateKeywords.spec.js index a9f18e5964..c61593e8b5 100644 --- a/aio/tools/transforms/angular.io-package/processors/generateKeywords.spec.js +++ b/aio/tools/transforms/angular-base-package/processors/generateKeywords.spec.js @@ -10,7 +10,7 @@ const mockReadFilesProcessor = { describe('generateKeywords processor', () => { it('should be available on the injector', () => { - const dgeni = new Dgeni([testPackage('angular.io-package')]); + const dgeni = new Dgeni([testPackage('angular-base-package')]); const injector = dgeni.configureInjector(); const processor = injector.get('generateKeywordsProcessor'); expect(processor.$process).toBeDefined(); diff --git a/aio/tools/transforms/angular.io-package/readers/json.js b/aio/tools/transforms/angular-base-package/readers/json.js similarity index 100% rename from aio/tools/transforms/angular.io-package/readers/json.js rename to aio/tools/transforms/angular-base-package/readers/json.js diff --git a/aio/tools/transforms/angular.io-package/rendering/indentForMarkdown.js b/aio/tools/transforms/angular-base-package/rendering/indentForMarkdown.js similarity index 100% rename from aio/tools/transforms/angular.io-package/rendering/indentForMarkdown.js rename to aio/tools/transforms/angular-base-package/rendering/indentForMarkdown.js diff --git a/aio/tools/transforms/angular.io-package/rendering/toId.js b/aio/tools/transforms/angular-base-package/rendering/toId.js similarity index 100% rename from aio/tools/transforms/angular.io-package/rendering/toId.js rename to aio/tools/transforms/angular-base-package/rendering/toId.js diff --git a/aio/tools/transforms/angular.io-package/rendering/toId.spec.js b/aio/tools/transforms/angular-base-package/rendering/toId.spec.js similarity index 100% rename from aio/tools/transforms/angular.io-package/rendering/toId.spec.js rename to aio/tools/transforms/angular-base-package/rendering/toId.spec.js diff --git a/aio/tools/transforms/angular.io-package/rendering/trimBlankLines.js b/aio/tools/transforms/angular-base-package/rendering/trimBlankLines.js similarity index 100% rename from aio/tools/transforms/angular.io-package/rendering/trimBlankLines.js rename to aio/tools/transforms/angular-base-package/rendering/trimBlankLines.js diff --git a/aio/tools/transforms/angular.io-package/rendering/trimBlankLines.spec.js b/aio/tools/transforms/angular-base-package/rendering/trimBlankLines.spec.js similarity index 100% rename from aio/tools/transforms/angular.io-package/rendering/trimBlankLines.spec.js rename to aio/tools/transforms/angular-base-package/rendering/trimBlankLines.spec.js diff --git a/aio/tools/transforms/angular-content-package/index.js b/aio/tools/transforms/angular-content-package/index.js new file mode 100644 index 0000000000..013e020a00 --- /dev/null +++ b/aio/tools/transforms/angular-content-package/index.js @@ -0,0 +1,117 @@ +/** + * @license + * Copyright Google Inc. All Rights Reserved. + * + * Use of this source code is governed by an MIT-style license that can be + * found in the LICENSE file at https://angular.io/license + */ +const path = require('path'); +const Package = require('dgeni').Package; + +const basePackage = require('../angular-base-package'); +const contentPackage = require('../content-package'); + +const { CONTENTS_PATH, OUTPUT_PATH } = require('../config'); + +module.exports = new Package('angular-content', [basePackage, contentPackage]) + + // Register the processors + .processor(require('./processors/copyContentAssets')) + + .factory(require('./services/copyFolder')) + + // Where do we get the source files? + .config(function(readFilesProcessor, collectExamples, copyContentAssetsProcessor) { + + readFilesProcessor.sourceFiles = readFilesProcessor.sourceFiles.concat([ + { + basePath: CONTENTS_PATH, + include: CONTENTS_PATH + '/{cookbook,guide,tutorial}/**/*.md', + fileReader: 'contentFileReader' + }, + { + basePath: CONTENTS_PATH + '/marketing', + include: CONTENTS_PATH + '/marketing/**/*.{html,md}', + fileReader: 'contentFileReader' + }, + { + basePath: CONTENTS_PATH, + include: CONTENTS_PATH + '/*.md', + exclude: [CONTENTS_PATH + '/index.md'], + fileReader: 'contentFileReader' + }, + { + basePath: CONTENTS_PATH, + include: CONTENTS_PATH + '/examples/**/*', + exclude: [ + '**/*plnkr.no-link.html', + '**/node_modules/**', + // boilerplate files + '**/*/src/systemjs-angular-loader.js', + '**/*/src/systemjs.config.js', + '**/*/src/tsconfig.json', + '**/*/bs-config.e2e.json', + '**/*/bs-config.json', + '**/*/package.json', + '**/*/tslint.json', + // example files + '**/_test-output', + '**/protractor-helpers.js', + '**/e2e-spec.js', + '**/ts/**/*.js', + '**/js-es6*/**/*.js', + '**/ts-snippets/**/*.js', + ], + fileReader: 'exampleFileReader' + }, + { + basePath: CONTENTS_PATH, + include: CONTENTS_PATH + '/navigation.json', + fileReader: 'jsonFileReader' + }, + { + basePath: CONTENTS_PATH, + include: CONTENTS_PATH + '/marketing/contributors.json', + fileReader: 'jsonFileReader' + }, + { + basePath: CONTENTS_PATH, + include: CONTENTS_PATH + '/marketing/resources.json', + fileReader: 'jsonFileReader' + }, + ]); + + collectExamples.exampleFolders.push('examples'); + + copyContentAssetsProcessor.assetMappings.push( + { from: path.resolve(CONTENTS_PATH, 'images'), to: path.resolve(OUTPUT_PATH, 'images') } + ); + }) + + + // Configure jsdoc-style tag parsing + .config(function(inlineTagProcessor) { + inlineTagProcessor.inlineTagDefinitions.push(require('./inline-tag-defs/anchor')); + }) + + + .config(function(computePathsProcessor) { + + // Replace any path templates inherited from other packages + // (we want full and transparent control) + computePathsProcessor.pathTemplates = computePathsProcessor.pathTemplates.concat([ + { + docTypes: ['content'], + getPath: (doc) => `${doc.id.replace(/\/index$/, '')}`, + outputPathTemplate: '${path}.json' + }, + {docTypes: ['navigation-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}, + {docTypes: ['contributors-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}, + {docTypes: ['resources-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'} + ]); + }) + + // We want the content files to be converted + .config(function(convertToJsonProcessor) { + convertToJsonProcessor.docTypes.push('content'); + }); diff --git a/aio/tools/transforms/angular.io-package/inline-tag-defs/anchor.js b/aio/tools/transforms/angular-content-package/inline-tag-defs/anchor.js similarity index 100% rename from aio/tools/transforms/angular.io-package/inline-tag-defs/anchor.js rename to aio/tools/transforms/angular-content-package/inline-tag-defs/anchor.js diff --git a/aio/tools/transforms/angular.io-package/processors/copyContentAssets.js b/aio/tools/transforms/angular-content-package/processors/copyContentAssets.js similarity index 100% rename from aio/tools/transforms/angular.io-package/processors/copyContentAssets.js rename to aio/tools/transforms/angular-content-package/processors/copyContentAssets.js diff --git a/aio/tools/transforms/angular.io-package/processors/copyContentAssets.spec.js b/aio/tools/transforms/angular-content-package/processors/copyContentAssets.spec.js similarity index 93% rename from aio/tools/transforms/angular.io-package/processors/copyContentAssets.spec.js rename to aio/tools/transforms/angular-content-package/processors/copyContentAssets.spec.js index 04ac065527..df2d85769c 100644 --- a/aio/tools/transforms/angular.io-package/processors/copyContentAssets.spec.js +++ b/aio/tools/transforms/angular-content-package/processors/copyContentAssets.spec.js @@ -6,7 +6,7 @@ describe('extractDecoratedClasses processor', function() { let dgeni, injector, processor; beforeEach(function() { - dgeni = new Dgeni([testPackage('angular.io-package')]); + dgeni = new Dgeni([testPackage('angular-content-package')]); injector = dgeni.configureInjector(); processor = injector.get('copyContentAssetsProcessor'); }); diff --git a/aio/tools/transforms/angular.io-package/services/copyFolder.js b/aio/tools/transforms/angular-content-package/services/copyFolder.js similarity index 100% rename from aio/tools/transforms/angular.io-package/services/copyFolder.js rename to aio/tools/transforms/angular-content-package/services/copyFolder.js diff --git a/aio/tools/transforms/angular.io-package/index.js b/aio/tools/transforms/angular.io-package/index.js index 68c598f16b..94d67eb73f 100644 --- a/aio/tools/transforms/angular.io-package/index.js +++ b/aio/tools/transforms/angular.io-package/index.js @@ -5,303 +5,20 @@ * Use of this source code is governed by an MIT-style license that can be * found in the LICENSE file at https://angular.io/license */ -const path = require('path'); -const fs = require('fs'); const Package = require('dgeni').Package; - -const jsdocPackage = require('dgeni-packages/jsdoc'); -const nunjucksPackage = require('dgeni-packages/nunjucks'); -const typescriptPackage = require('dgeni-packages/typescript'); const gitPackage = require('dgeni-packages/git'); -const linksPackage = require('../links-package'); -const examplesPackage = require('../examples-package'); -const targetPackage = require('../target-package'); -const contentPackage = require('../content-package'); -const remarkPackage = require('../remark-package'); +const apiPackage = require('../angular-api-package'); +const contentPackage = require('../angular-content-package'); -const PROJECT_ROOT = path.resolve(__dirname, '../../../..'); -const API_SOURCE_PATH = path.resolve(PROJECT_ROOT, 'packages'); -const AIO_PATH = path.resolve(PROJECT_ROOT, 'aio'); -const CONTENTS_PATH = path.resolve(AIO_PATH, 'content'); -const TEMPLATES_PATH = path.resolve(AIO_PATH, 'tools/transforms/templates'); -const OUTPUT_PATH = path.resolve(AIO_PATH, 'src/content'); -const DOCS_OUTPUT_PATH = path.resolve(OUTPUT_PATH, 'docs'); +module.exports = new Package('angular.io', [gitPackage, apiPackage, contentPackage]) -module.exports = - new Package( - 'angular.io', [ - jsdocPackage, nunjucksPackage, typescriptPackage, linksPackage, examplesPackage, - gitPackage, targetPackage, contentPackage, remarkPackage - ]) + // This processor relies upon the versionInfo. See below... + .processor(require('./processors/processNavigationMap')) - // Register the processors - .processor(require('./processors/convertPrivateClassesToInterfaces')) - .processor(require('./processors/generateApiListDoc')) - .processor(require('./processors/generateKeywords')) - .processor(require('./processors/createOverviewDump')) - .processor(require('./processors/checkUnbalancedBackTicks')) - .processor(require('./processors/addNotYetDocumentedProperty')) - .processor(require('./processors/mergeDecoratorDocs')) - .processor(require('./processors/extractDecoratedClasses')) - .processor(require('./processors/matchUpDirectiveDecorators')) - .processor(require('./processors/filterMemberDocs')) - .processor(require('./processors/convertToJson')) - .processor(require('./processors/markBarredODocsAsPrivate')) - .processor(require('./processors/filterPrivateDocs')) - .processor(require('./processors/filterIgnoredDocs')) - .processor(require('./processors/fixInternalDocumentLinks')) - .processor(require('./processors/processNavigationMap')) - .processor(require('./processors/copyContentAssets')) + // We don't include this in the angular-base package because the `versionInfo` stuff + // accesses the file system and git, which is slow. + .config(function(renderDocsProcessor, versionInfo) { + // Add the version data to the renderer, for use in things like github links + renderDocsProcessor.extraData.versionInfo = versionInfo; - // overrides base packageInfo and returns the one for the 'angular/angular' repo. - .factory('packageInfo', function() { return require(path.resolve(PROJECT_ROOT, 'package.json')); }) - .factory(require('./readers/json')) - .factory(require('./services/copyFolder')) - - .config(function(checkAnchorLinksProcessor) { - // TODO: re-enable - checkAnchorLinksProcessor.$enabled = false; - }) - - // Where do we get the source files? - .config(function( - readTypeScriptModules, readFilesProcessor, collectExamples, generateKeywordsProcessor, jsonFileReader) { - - // API files are typescript - readTypeScriptModules.basePath = API_SOURCE_PATH; - readTypeScriptModules.ignoreExportsMatching = [/^_/]; - readTypeScriptModules.hidePrivateMembers = true; - readFilesProcessor.fileReaders.push(jsonFileReader); - readTypeScriptModules.sourceFiles = [ - 'common/index.ts', - 'common/testing/index.ts', - 'core/index.ts', - 'core/testing/index.ts', - 'forms/index.ts', - 'http/index.ts', - 'http/testing/index.ts', - 'platform-browser/index.ts', - 'platform-browser/testing/index.ts', - 'platform-browser-dynamic/index.ts', - 'platform-browser-dynamic/testing/index.ts', - 'platform-server/index.ts', - 'platform-server/testing/index.ts', - 'platform-webworker/index.ts', - 'platform-webworker-dynamic/index.ts', - 'router/index.ts', - 'router/testing/index.ts', - 'upgrade/index.ts', - 'upgrade/static.ts', - ]; - - readFilesProcessor.basePath = PROJECT_ROOT; - readFilesProcessor.sourceFiles = [ - { - basePath: CONTENTS_PATH, - include: CONTENTS_PATH + '/{cookbook,guide,tutorial}/**/*.md', - fileReader: 'contentFileReader' - }, - { - basePath: CONTENTS_PATH + '/marketing', - include: CONTENTS_PATH + '/marketing/**/*.{html,md}', - fileReader: 'contentFileReader' - }, - { - basePath: CONTENTS_PATH, - include: CONTENTS_PATH + '/*.md', - exclude: [CONTENTS_PATH + '/index.md'], - fileReader: 'contentFileReader' - }, - { - basePath: API_SOURCE_PATH, - include: API_SOURCE_PATH + '/examples/**/*', - fileReader: 'exampleFileReader' - }, - { - basePath: CONTENTS_PATH, - include: CONTENTS_PATH + '/examples/**/*', - exclude: [ - '**/*plnkr.no-link.html', - '**/node_modules/**', - // boilerplate files - '**/*/src/systemjs-angular-loader.js', - '**/*/src/systemjs.config.js', - '**/*/src/tsconfig.json', - '**/*/bs-config.e2e.json', - '**/*/bs-config.json', - '**/*/package.json', - '**/*/tslint.json', - // example files - '**/_test-output', - '**/protractor-helpers.js', - '**/e2e-spec.js', - '**/ts/**/*.js', - '**/js-es6*/**/*.js', - '**/ts-snippets/**/*.js', - ], - fileReader: 'exampleFileReader' - }, - { - basePath: CONTENTS_PATH, - include: CONTENTS_PATH + '/navigation.json', - fileReader: 'jsonFileReader' - }, - { - basePath: CONTENTS_PATH, - include: CONTENTS_PATH + '/marketing/contributors.json', - fileReader: 'jsonFileReader' - }, - { - basePath: CONTENTS_PATH, - include: CONTENTS_PATH + '/marketing/resources.json', - fileReader: 'jsonFileReader' - }, - ]; - - collectExamples.exampleFolders = ['examples', 'examples']; - - generateKeywordsProcessor.ignoreWordsFile = 'aio/tools/transforms/angular.io-package/ignore.words'; - generateKeywordsProcessor.docTypesToIgnore = ['example-region']; - }) - - // Ignore certain problematic files - .config(function(filterIgnoredDocs) { - filterIgnoredDocs.ignore = [ - /\/VERSION$/ // Ignore the `VERSION` const, since it would be written to the same file as the `Version` class - ]; - }) - - // Where do we write the output files? - .config(function(writeFilesProcessor) { writeFilesProcessor.outputFolder = DOCS_OUTPUT_PATH; }) - - - // Target environments - .config(function(targetEnvironments) { - const ALLOWED_LANGUAGES = ['ts', 'js', 'dart']; - const TARGET_LANGUAGE = 'ts'; - - ALLOWED_LANGUAGES.forEach(target => targetEnvironments.addAllowed(target)); - targetEnvironments.activate(TARGET_LANGUAGE); - - // TODO: we may need to do something with `linkDocsInlineTagDef` - }) - - - // Configure jsdoc-style tag parsing - .config(function(parseTagsProcessor, getInjectables, inlineTagProcessor) { - // Load up all the tag definitions in the tag-defs folder - parseTagsProcessor.tagDefinitions = - parseTagsProcessor.tagDefinitions.concat(getInjectables(requireFolder('./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 = []; - } - }); - - inlineTagProcessor.inlineTagDefinitions.push(require('./inline-tag-defs/anchor')); - }) - - - - // Configure nunjucks rendering of docs via templates - .config(function( - renderDocsProcessor, versionInfo, templateFinder, templateEngine, getInjectables) { - - // Where to find the templates for the doc rendering - templateFinder.templateFolders = [TEMPLATES_PATH]; - - // Standard patterns for matching docs to templates - templateFinder.templatePatterns = [ - '${ doc.template }', '${ doc.id }.${ doc.docType }.template.html', - '${ doc.id }.template.html', '${ doc.docType }.template.html', - '${ doc.id }.${ doc.docType }.template.js', '${ doc.id }.template.js', - '${ doc.docType }.template.js', '${ doc.id }.${ doc.docType }.template.json', - '${ doc.id }.template.json', '${ doc.docType }.template.json', 'common.template.html' - ]; - - // Nunjucks and Angular conflict in their template bindings so change Nunjucks - templateEngine.config.tags = {variableStart: '{$', variableEnd: '$}'}; - - templateEngine.filters = - templateEngine.filters.concat(getInjectables(requireFolder('./rendering'))); - - // Add the version data to the renderer, for use in things like github links - renderDocsProcessor.extraData.versionInfo = versionInfo; - - // helpers are made available to the nunjucks templates - renderDocsProcessor.helpers.relativePath = function(from, to) { - return path.relative(from, to); - }; - }) - - - - // We are not going to be relaxed about ambiguous links - .config(function(getLinkInfo) { - getLinkInfo.useFirstAmbiguousLink = false; - }) - - - - .config(function( - computeIdsProcessor, computePathsProcessor, EXPORT_DOC_TYPES, generateApiListDoc, - generateKeywordsProcessor) { - - const API_SEGMENT = 'api'; - const APP_SEGMENT = 'app'; - - generateApiListDoc.outputFolder = API_SEGMENT; - generateKeywordsProcessor.outputFolder = APP_SEGMENT; - - // Replace any path templates inherited from other packages - // (we want full and transparent control) - computePathsProcessor.pathTemplates = [ - { - docTypes: ['module'], - getPath: function computeModulePath(doc) { - doc.moduleFolder = `${API_SEGMENT}/${doc.id.replace(/\/index$/, '')}`; - return doc.moduleFolder; - }, - outputPathTemplate: '${moduleFolder}.json' - }, - { - docTypes: EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe']), - pathTemplate: '${moduleDoc.moduleFolder}/${name}', - outputPathTemplate: '${moduleDoc.moduleFolder}/${name}.json', - }, - {docTypes: ['example-region'], getOutputPath: function() {}}, - { - docTypes: ['content'], - getPath: (doc) => `${doc.id.replace(/\/index$/, '')}`, - outputPathTemplate: '${path}.json' - }, - {docTypes: ['navigation-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}, - {docTypes: ['contributors-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}, - {docTypes: ['resources-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'} - ]; - }) - - .config(function(convertToJsonProcessor, EXPORT_DOC_TYPES) { - convertToJsonProcessor.docTypes = EXPORT_DOC_TYPES.concat([ - 'content', 'decorator', 'directive', 'pipe', 'module' - ]); - }) - - .config(function(copyContentAssetsProcessor) { - copyContentAssetsProcessor.assetMappings.push( - { from: path.resolve(CONTENTS_PATH, 'images'), to: path.resolve(OUTPUT_PATH, 'images') } - ); - }); - - -function requireFolder(folderPath) { - const absolutePath = path.resolve(__dirname, folderPath); - return fs.readdirSync(absolutePath) - .filter(p => !/[._]spec\.js$/.test(p)) // ignore spec files - .map(p => require(path.resolve(absolutePath, p))); -} + }); diff --git a/aio/tools/transforms/authors-package/api-package.js b/aio/tools/transforms/authors-package/api-package.js index bbac81d113..b591b50dd4 100644 --- a/aio/tools/transforms/authors-package/api-package.js +++ b/aio/tools/transforms/authors-package/api-package.js @@ -6,7 +6,9 @@ * found in the LICENSE file at https://angular.io/license */ const Package = require('dgeni').Package; -const { basePackage, API_SOURCE_PATH } = require('./base-package'); +const apiPackage = require('../angular-api-package'); +const { API_SOURCE_PATH } = require('../config'); + const packageMap = { common: ['common/index.ts', 'common/testing/index.ts'], core: ['core/index.ts', 'core/testing/index.ts'], @@ -20,22 +22,12 @@ const packageMap = { router: ['router/index.ts', 'router/testing/index.ts'], upgrade: ['upgrade/index.ts', 'upgrade/static.ts'] }; + + function createPackage(packageName) { - return new Package('author-api', [require('dgeni-packages/typescript'), basePackage]) - .processor(require('../angular.io-package/processors/convertPrivateClassesToInterfaces')) - .processor(require('../angular.io-package/processors/mergeDecoratorDocs')) - .processor(require('../angular.io-package/processors/extractDecoratedClasses')) - .processor(require('../angular.io-package/processors/matchUpDirectiveDecorators')) - .processor(require('../angular.io-package/processors/filterMemberDocs')) - .processor(require('../angular.io-package/processors/markBarredODocsAsPrivate')) - .processor(require('../angular.io-package/processors/filterPrivateDocs')) - .processor(require('../angular.io-package/processors/filterIgnoredDocs')) + return new Package('author-api', [apiPackage]) .config(function(readTypeScriptModules) { - // API files are typescript - readTypeScriptModules.basePath = API_SOURCE_PATH; - readTypeScriptModules.ignoreExportsMatching = [/^_/]; - readTypeScriptModules.hidePrivateMembers = true; readTypeScriptModules.sourceFiles = packageMap[packageName]; }) .config(function(readFilesProcessor) { @@ -46,43 +38,6 @@ function createPackage(packageName) { fileReader: 'exampleFileReader' } ]; - }) - .config(function( - computeIdsProcessor, computePathsProcessor, EXPORT_DOC_TYPES) { - - const API_SEGMENT = 'api'; - - // Replace any path templates inherited from other packages - // (we want full and transparent control) - computePathsProcessor.pathTemplates = [ - { - docTypes: ['module'], - getPath: function computeModulePath(doc) { - doc.moduleFolder = `${API_SEGMENT}/${doc.id.replace(/\/index$/, '')}`; - return doc.moduleFolder; - }, - outputPathTemplate: '${moduleFolder}.json' - }, - { - docTypes: EXPORT_DOC_TYPES.concat(['decorator', 'directive', 'pipe']), - pathTemplate: '${moduleDoc.moduleFolder}/${name}', - outputPathTemplate: '${moduleDoc.moduleFolder}/${name}.json', - }, - {docTypes: ['example-region'], getOutputPath: function() {}}, - { - docTypes: ['content'], - getPath: (doc) => `${doc.id.replace(/\/index$/, '')}`, - outputPathTemplate: '${path}.json' - }, - {docTypes: ['navigation-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}, - {docTypes: ['contributors-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'} - ]; - }) - - .config(function(convertToJsonProcessor, EXPORT_DOC_TYPES) { - convertToJsonProcessor.docTypes = EXPORT_DOC_TYPES.concat([ - 'content', 'decorator', 'directive', 'pipe', 'module' - ]); }); } diff --git a/aio/tools/transforms/authors-package/base-package.js b/aio/tools/transforms/authors-package/base-package.js deleted file mode 100644 index e0ab07fc56..0000000000 --- a/aio/tools/transforms/authors-package/base-package.js +++ /dev/null @@ -1,194 +0,0 @@ -/** - * @license - * Copyright Google Inc. All Rights Reserved. - * - * Use of this source code is governed by an MIT-style license that can be - * found in the LICENSE file at https://angular.io/license - */ -/* eslint no-console: "off" */ -const path = require('path'); -const fs = require('fs'); -const Package = require('dgeni').Package; - -const jsdocPackage = require('dgeni-packages/jsdoc'); -const nunjucksPackage = require('dgeni-packages/nunjucks'); -const linksPackage = require('../links-package'); -const examplesPackage = require('../examples-package'); -const targetPackage = require('../target-package'); -const contentPackage = require('../content-package'); -const remarkPackage = require('../remark-package'); - -const PROJECT_ROOT = path.resolve(__dirname, '../../../..'); -const API_SOURCE_PATH = path.resolve(PROJECT_ROOT, 'packages'); -const AIO_PATH = path.resolve(PROJECT_ROOT, 'aio'); -const CONTENTS_PATH = path.resolve(AIO_PATH, 'content'); -const TEMPLATES_PATH = path.resolve(AIO_PATH, 'tools/transforms/templates'); -const OUTPUT_PATH = path.resolve(AIO_PATH, 'src/content'); -const DOCS_OUTPUT_PATH = path.resolve(OUTPUT_PATH, 'docs'); - -const basePackage = new Package('authors-base', [ - jsdocPackage, nunjucksPackage, linksPackage, examplesPackage, - targetPackage, contentPackage, remarkPackage -]) - - // Register the processors - .processor(require('../angular.io-package/processors/checkUnbalancedBackTicks')) - .processor(require('../angular.io-package/processors/convertToJson')) - .processor(require('../angular.io-package/processors/fixInternalDocumentLinks')) - .processor(require('../angular.io-package/processors/copyContentAssets')) - - // overrides base packageInfo and returns the one for the 'angular/angular' repo. - .factory('packageInfo', function() { return require(path.resolve(PROJECT_ROOT, 'package.json')); }) - .factory(require('../angular.io-package/readers/json')) - .factory(require('../angular.io-package/services/copyFolder')) - - .config(function(checkAnchorLinksProcessor) { - // TODO: re-enable - checkAnchorLinksProcessor.$enabled = false; - }) - - // Where do we get the source files? - .config(function(readFilesProcessor, collectExamples, jsonFileReader) { - - readFilesProcessor.basePath = PROJECT_ROOT; - readFilesProcessor.fileReaders.push(jsonFileReader); - collectExamples.exampleFolders = ['examples']; - }) - - // Where do we write the output files? - .config(function(writeFilesProcessor) { writeFilesProcessor.outputFolder = DOCS_OUTPUT_PATH; }) - - - // Target environments - // TODO: remove this stuff when we have no more target inline tags - .config(function(targetEnvironments) { - const ALLOWED_LANGUAGES = ['ts', 'js', 'dart']; - const TARGET_LANGUAGE = 'ts'; - - ALLOWED_LANGUAGES.forEach(target => targetEnvironments.addAllowed(target)); - targetEnvironments.activate(TARGET_LANGUAGE); - }) - - - // Configure jsdoc-style tag parsing - .config(function(parseTagsProcessor, getInjectables, inlineTagProcessor) { - // Load up all the tag definitions in the tag-defs folder - parseTagsProcessor.tagDefinitions = - parseTagsProcessor.tagDefinitions.concat(getInjectables(requireFolder('../angular.io-package/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 = []; - } - }); - - inlineTagProcessor.inlineTagDefinitions.push(require('../angular.io-package/inline-tag-defs/anchor')); - }) - - // Configure nunjucks rendering of docs via templates - .config(function( - renderDocsProcessor, templateFinder, templateEngine, getInjectables) { - - // Where to find the templates for the doc rendering - templateFinder.templateFolders = [TEMPLATES_PATH]; - - // Standard patterns for matching docs to templates - templateFinder.templatePatterns = [ - '${ doc.template }', '${ doc.id }.${ doc.docType }.template.html', - '${ doc.id }.template.html', '${ doc.docType }.template.html', - '${ doc.id }.${ doc.docType }.template.js', '${ doc.id }.template.js', - '${ doc.docType }.template.js', '${ doc.id }.${ doc.docType }.template.json', - '${ doc.id }.template.json', '${ doc.docType }.template.json', 'common.template.html' - ]; - - // Nunjucks and Angular conflict in their template bindings so change Nunjucks - templateEngine.config.tags = {variableStart: '{$', variableEnd: '$}'}; - - templateEngine.filters = - templateEngine.filters.concat(getInjectables(requireFolder('../angular.io-package/rendering'))); - - // helpers are made available to the nunjucks templates - renderDocsProcessor.helpers.relativePath = function(from, to) { - return path.relative(from, to); - }; - }) - - // We are not going to be relaxed about ambiguous links - .config(function(getLinkInfo) { - getLinkInfo.useFirstAmbiguousLink = false; - }) - - .config(function(computeIdsProcessor, computePathsProcessor) { - - // Replace any path templates inherited from other packages - // (we want full and transparent control) - computePathsProcessor.pathTemplates = [ - {docTypes: ['example-region'], getOutputPath: function() {}}, - { - docTypes: ['content'], - getPath: (doc) => `${doc.id.replace(/\/index$/, '')}`, - outputPathTemplate: '${path}.json' - }, - {docTypes: ['navigation-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}, - {docTypes: ['contributors-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'}, - {docTypes: ['resources-json'], pathTemplate: '${id}', outputPathTemplate: '../${id}.json'} - ]; - }) - - .config(function(convertToJsonProcessor) { - convertToJsonProcessor.docTypes = ['content']; - }) - - .config(function(copyContentAssetsProcessor) { - copyContentAssetsProcessor.assetMappings.push( - { from: path.resolve(CONTENTS_PATH, 'images'), to: path.resolve(OUTPUT_PATH, 'images') } - ); - }); - -function requireFolder(folderPath) { - const absolutePath = path.resolve(__dirname, folderPath); - return fs.readdirSync(absolutePath) - .filter(p => !/[._]spec\.js$/.test(p)) // ignore spec files - .map(p => require(path.resolve(absolutePath, p))); -} - -function getBoilerPlateExcludes() { - return [ - '**/*plnkr.no-link.html', - '**/node_modules/**', - // _boilerplate files - '**/_boilerplate/**', - '**/*/src/styles.css', - '**/*/src/systemjs-angular-loader.js', - '**/*/src/systemjs.config.js', - '**/*/src/tsconfig.json', - '**/*/bs-config.e2e.json', - '**/*/bs-config.json', - '**/*/package.json', - '**/*/tslint.json', - // example files - '**/_test-output', - '**/protractor-helpers.js', - '**/e2e-spec.js', - '**/ts/**/*.js', - '**/js-es6*/**/*.js', - '**/ts-snippets/**/*.js', - ]; -} - -module.exports = { - basePackage, - PROJECT_ROOT, - API_SOURCE_PATH, - AIO_PATH, - CONTENTS_PATH, - TEMPLATES_PATH, - OUTPUT_PATH, - DOCS_OUTPUT_PATH, - requireFolder, - getBoilerPlateExcludes -}; diff --git a/aio/tools/transforms/authors-package/guide-package.js b/aio/tools/transforms/authors-package/guide-package.js index dbf155c184..8bac6f4ba4 100644 --- a/aio/tools/transforms/authors-package/guide-package.js +++ b/aio/tools/transforms/authors-package/guide-package.js @@ -9,9 +9,10 @@ /* eslint no-console: "off" */ const Package = require('dgeni').Package; -const { basePackage, CONTENTS_PATH } = require('./base-package'); +const contentPackage = require('../angular-content-package'); const { readFileSync } = require('fs'); const { resolve } = require('canonical-path'); +const { CONTENTS_PATH } = require('../config'); function createPackage(guideName) { @@ -25,7 +26,7 @@ function createPackage(guideName) { console.log(examples.map(example => ' - ' + example).join('\n')); } - return new Package('author-guide', [basePackage]) + return new Package('author-guide', [contentPackage]) .config(function(readFilesProcessor) { readFilesProcessor.sourceFiles = [ { @@ -42,5 +43,4 @@ function createPackage(guideName) { }); } - module.exports = { createPackage }; \ No newline at end of file diff --git a/aio/tools/transforms/authors-package/index.js b/aio/tools/transforms/authors-package/index.js index 0e97a319a6..31a5b89a7d 100644 --- a/aio/tools/transforms/authors-package/index.js +++ b/aio/tools/transforms/authors-package/index.js @@ -14,18 +14,20 @@ function createPackage(changedFile) { return require('./marketing-package').createPackage(); } - const tutorialMatch = /^aio\/content\/tutorial\/|^aio\/content\/examples\/toh-\d/.exec(changedFile); - if (tutorialMatch) { + const tutorialMatch = /^aio\/content\/tutorial\/([^.]+)\.md/.exec(changedFile); + const tutorialExampleMatch = /^aio\/content\/examples\/(toh-[^\/]+)\//.exec(changedFile); + if (tutorialMatch || tutorialExampleMatch) { + const tutorialName = tutorialMatch && tutorialMatch[1] || tutorialExampleMatch[1]; console.log('Building tutorial docs'); - return require('./tutorial-package').createPackage(); + return require('./tutorial-package').createPackage(tutorialName); } - const guideMatch = /^aio\/content\/guide\/([^\.]+)\.md/.exec(changedFile); + const guideMatch = /^aio\/content\/guide\/([^.]+)\.md/.exec(changedFile); const exampleMatch = /^aio\/content\/examples\/(?:cb-)?([^\/]+)\//.exec(changedFile); if (guideMatch || exampleMatch) { - const exampleName = guideMatch && guideMatch[1] || exampleMatch[1]; - console.log(`Building guide doc: ${exampleName}.md`); - return require('./guide-package').createPackage(exampleName); + const guideName = guideMatch && guideMatch[1] || exampleMatch[1]; + console.log(`Building guide doc: ${guideName}.md`); + return require('./guide-package').createPackage(guideName); } const apiExamplesMatch = /^packages\/examples\/([^\/]+)\//.exec(changedFile); @@ -38,9 +40,13 @@ function createPackage(changedFile) { } module.exports = { - generateDocs: function(changedFile) { + generateDocs: function(changedFile, options = {}) { const {Dgeni} = require('dgeni'); - var dgeni = new Dgeni([createPackage(changedFile)]); + const package = createPackage(changedFile); + if (options.silent) { + package.config(function(log) { log.level = 'error'; }); + } + var dgeni = new Dgeni([package]); const start = Date.now(); return dgeni.generate() .then( diff --git a/aio/tools/transforms/authors-package/index.spec.js b/aio/tools/transforms/authors-package/index.spec.js index 5d9c5e2be9..57f54d763d 100644 --- a/aio/tools/transforms/authors-package/index.spec.js +++ b/aio/tools/transforms/authors-package/index.spec.js @@ -16,7 +16,7 @@ describe('authors-package', () => { }); it('should generate marketing docs if the "fileChanged" is a marketing doc', (done) => { - generateDocs('aio/content/marketing/about.html').then(() => { + generateDocs('aio/content/marketing/about.html', { silent: true }).then(() => { expect(fs.writeFile).toHaveBeenCalled(); expect(files).toContain(resolve(outputPath, 'about.json')); expect(files).toContain(resolve(outputPath, '../navigation.json')); @@ -27,49 +27,31 @@ describe('authors-package', () => { }, 4000); it('should generate tutorial docs if the "fileChanged" is a tutorial doc', (done) => { - generateDocs('aio/content/tutorial/toh-pt5.md').then(() => { + generateDocs('aio/content/tutorial/toh-pt5.md', { silent: true }).then(() => { expect(fs.writeFile).toHaveBeenCalled(); - expect(files).toContain(resolve(outputPath, 'tutorial.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt1.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt2.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt3.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt4.json')); expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt5.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt6.json')); done(); }); }, 4000); it('should generate tutorial docs if the "fileChanged" is the tutorial index', (done) => { - generateDocs('aio/content/tutorial/index.md').then(() => { + generateDocs('aio/content/tutorial/index.md', { silent: true }).then(() => { expect(fs.writeFile).toHaveBeenCalled(); expect(files).toContain(resolve(outputPath, 'tutorial.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt1.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt2.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt3.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt4.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt5.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt6.json')); done(); }); }, 4000); it('should generate tutorial docs if the "fileChanged" is a tutorial example', (done) => { - generateDocs('aio/content/examples/toh-3/app/app.component.1.html').then(() => { + generateDocs('aio/content/examples/toh-pt3/app/app.component.1.html', { silent: true }).then(() => { expect(fs.writeFile).toHaveBeenCalled(); - expect(files).toContain(resolve(outputPath, 'tutorial.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt1.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt2.json')); expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt3.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt4.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt5.json')); - expect(files).toContain(resolve(outputPath, 'tutorial/toh-pt6.json')); done(); }); }, 4000); it('should generate guide doc if the "fileChanged" is a guide doc', (done) => { - generateDocs('aio/content/guide/architecture.md').then(() => { + generateDocs('aio/content/guide/architecture.md', { silent: true }).then(() => { expect(fs.writeFile).toHaveBeenCalled(); expect(files).toContain(resolve(outputPath, 'guide/architecture.json')); done(); @@ -77,7 +59,7 @@ describe('authors-package', () => { }, 4000); it('should generate guide doc if the "fileChanged" is a guide example', (done) => { - generateDocs('aio/content/examples/architecture/src/app/app.module.ts').then(() => { + generateDocs('aio/content/examples/architecture/src/app/app.module.ts', { silent: true }).then(() => { expect(fs.writeFile).toHaveBeenCalled(); expect(files).toContain(resolve(outputPath, 'guide/architecture.json')); done(); @@ -85,7 +67,7 @@ describe('authors-package', () => { }, 4000); it('should generate API doc if the "fileChanged" is an API doc', (done) => { - generateDocs('packages/forms/src/form_builder.ts').then(() => { + generateDocs('packages/forms/src/form_builder.ts', { silent: true }).then(() => { expect(fs.writeFile).toHaveBeenCalled(); expect(files).toContain(resolve(outputPath, 'api/forms/FormBuilder.json')); done(); @@ -93,7 +75,7 @@ describe('authors-package', () => { }, 4000); it('should generate API doc if the "fileChanged" is an API example', (done) => { - generateDocs('packages/examples/forms/ts/formBuilder/form_builder_example.ts').then(() => { + generateDocs('packages/examples/forms/ts/formBuilder/form_builder_example.ts', { silent: true }).then(() => { expect(fs.writeFile).toHaveBeenCalled(); expect(files).toContain(resolve(outputPath, 'api/forms/FormBuilder.json')); done(); diff --git a/aio/tools/transforms/authors-package/marketing-package.js b/aio/tools/transforms/authors-package/marketing-package.js index 2a42b3d5de..30dac6b9d8 100644 --- a/aio/tools/transforms/authors-package/marketing-package.js +++ b/aio/tools/transforms/authors-package/marketing-package.js @@ -6,10 +6,11 @@ * found in the LICENSE file at https://angular.io/license */ const Package = require('dgeni').Package; -const { basePackage, CONTENTS_PATH } = require('./base-package'); +const contentPackage = require('../angular-content-package'); +const { CONTENTS_PATH } = require('../config'); function createPackage() { - return new Package('author-marketing', [basePackage]) + return new Package('author-marketing', [contentPackage]) .config(function(readFilesProcessor) { readFilesProcessor.sourceFiles = [ { diff --git a/aio/tools/transforms/authors-package/tutorial-package.js b/aio/tools/transforms/authors-package/tutorial-package.js index eb9b0de07d..5bc6cce023 100644 --- a/aio/tools/transforms/authors-package/tutorial-package.js +++ b/aio/tools/transforms/authors-package/tutorial-package.js @@ -5,22 +5,38 @@ * Use of this source code is governed by an MIT-style license that can be * found in the LICENSE file at https://angular.io/license */ -const Package = require('dgeni').Package; -const { basePackage, CONTENTS_PATH, getBoilerPlateExcludes } = require('./base-package'); -function createPackage() { - return new Package('author-tutorial', [basePackage]) +const Package = require('dgeni').Package; +const contentPackage = require('../angular-content-package'); +const { readFileSync } = require('fs'); +const { resolve } = require('canonical-path'); +const { CONTENTS_PATH } = require('../config'); + +/* eslint no-console: "off" */ + +function createPackage(tutorialName) { + + const tutorialFilePath = `${CONTENTS_PATH}/tutorial/${tutorialName}.md`; + const tutorialFile = readFileSync(tutorialFilePath, 'utf8'); + const examples = []; + tutorialFile.replace(/]*path="([^"]+)"/g, (_, path) => examples.push('examples/' + path)); + + if (examples.length) { + console.log('The following example files are referenced in this tutorial:'); + console.log(examples.map(example => ' - ' + example).join('\n')); + } + + return new Package('author-tutorial', [contentPackage]) .config(function(readFilesProcessor) { readFilesProcessor.sourceFiles = [ { basePath: CONTENTS_PATH, - include: CONTENTS_PATH + '/tutorial/**/*.md', + include: tutorialFilePath, fileReader: 'contentFileReader' }, { basePath: CONTENTS_PATH, - include: CONTENTS_PATH + '/examples/toh-*/**/*', - exclude: getBoilerPlateExcludes(), + include: examples.map(example => resolve(CONTENTS_PATH, example)), fileReader: 'exampleFileReader' } ]; diff --git a/aio/tools/transforms/config.js b/aio/tools/transforms/config.js new file mode 100644 index 0000000000..e42be6d2b7 --- /dev/null +++ b/aio/tools/transforms/config.js @@ -0,0 +1,20 @@ +const { resolve } = require('path'); +const { readdirSync } = require('fs'); + +const PROJECT_ROOT = resolve(__dirname, '../../..'); +const AIO_PATH = resolve(PROJECT_ROOT, 'aio'); +const TEMPLATES_PATH = resolve(AIO_PATH, 'tools/transforms/templates'); +const CONTENTS_PATH = resolve(AIO_PATH, 'content'); +const OUTPUT_PATH = resolve(AIO_PATH, 'src/content'); +const DOCS_OUTPUT_PATH = resolve(OUTPUT_PATH, 'docs'); +const API_SOURCE_PATH = resolve(PROJECT_ROOT, 'packages'); + +function requireFolder(dirname, folderPath) { + const absolutePath = resolve(dirname, folderPath); + return readdirSync(absolutePath) + .filter(p => !/[._]spec\.js$/.test(p)) // ignore spec files + .map(p => require(resolve(absolutePath, p))); +} + +module.exports = { PROJECT_ROOT, AIO_PATH, TEMPLATES_PATH, CONTENTS_PATH, OUTPUT_PATH, DOCS_OUTPUT_PATH, API_SOURCE_PATH, requireFolder }; + diff --git a/aio/tools/transforms/content-package/index.js b/aio/tools/transforms/content-package/index.js index cbe639697f..6e48da3d81 100644 --- a/aio/tools/transforms/content-package/index.js +++ b/aio/tools/transforms/content-package/index.js @@ -1,47 +1,39 @@ var Package = require('dgeni').Package; var jsdocPackage = require('dgeni-packages/jsdoc'); var linksPackage = require('../links-package'); -var path = require('canonical-path'); -var fs = require('fs'); +var { requireFolder } = require('../config'); // Define the dgeni package for generating the docs module.exports = new Package('content', [jsdocPackage, linksPackage]) - // Register the services and file readers - .factory(require('./readers/content')) + // Register the services and file readers + .factory(require('./readers/content')) - // Configure file reading - .config(function(readFilesProcessor, contentFileReader) { - readFilesProcessor.fileReaders.push(contentFileReader); - }) + // Configure file reading + .config(function(readFilesProcessor, contentFileReader) { + readFilesProcessor.fileReaders.push(contentFileReader); + }) - .config(function(parseTagsProcessor, getInjectables) { - parseTagsProcessor.tagDefinitions = parseTagsProcessor.tagDefinitions.concat( - getInjectables(requireFolder('./tag-defs'))); - }) + .config(function(parseTagsProcessor, getInjectables) { + parseTagsProcessor.tagDefinitions = parseTagsProcessor.tagDefinitions.concat( + getInjectables(requireFolder(__dirname, './tag-defs'))); + }) - // Configure ids and paths - .config(function(computeIdsProcessor) { + // Configure ids and paths + .config(function(computeIdsProcessor) { - computeIdsProcessor.idTemplates.push({ - docTypes: ['content'], - getId: function(doc) { - return doc.fileInfo - .relativePath - // path should be relative to `modules` folder - .replace(/.*\/?modules\//, '') - // path should not include `/docs/` - .replace(/\/docs\//, '/') - // path should not have a suffix - .replace(/\.\w*$/, ''); - }, - getAliases: function(doc) { return [doc.id]; } - }); - }); - -function requireFolder(folderPath) { - const absolutePath = path.resolve(__dirname, folderPath); - return fs.readdirSync(absolutePath) - .filter(p => !/[._]spec\.js$/.test(p)) // ignore spec files - .map(p => require(path.resolve(absolutePath, p))); -} + computeIdsProcessor.idTemplates.push({ + docTypes: ['content'], + getId: function(doc) { + return doc.fileInfo + .relativePath + // path should be relative to `modules` folder + .replace(/.*\/?modules\//, '') + // path should not include `/docs/` + .replace(/\/docs\//, '/') + // path should not have a suffix + .replace(/\.\w*$/, ''); + }, + getAliases: function(doc) { return [doc.id]; } + }); + });