From 7bad1d356dc8c88f72329b5f55ef2dc34ed7d856 Mon Sep 17 00:00:00 2001 From: George Kalpakas Date: Thu, 18 Oct 2018 14:32:32 +0300 Subject: [PATCH] build(docs-infra): only render code example content in one place (#26514) PR Close #26514 --- .../inline-tag-defs/example.js | 16 ++-- .../inline-tag-defs/example.spec.js | 89 +++++++++---------- .../services/getExampleRegion.js | 2 +- 3 files changed, 54 insertions(+), 53 deletions(-) diff --git a/aio/tools/transforms/examples-package/inline-tag-defs/example.js b/aio/tools/transforms/examples-package/inline-tag-defs/example.js index ad0480ca71..9b5f9a9cf0 100644 --- a/aio/tools/transforms/examples-package/inline-tag-defs/example.js +++ b/aio/tools/transforms/examples-package/inline-tag-defs/example.js @@ -11,7 +11,7 @@ var entities = require('entities'); * {@example core/application_spec.ts -region=hello-app -header='Sample component' } * @kind function */ -module.exports = function exampleInlineTagDef(parseArgString, createDocMessage, getExampleRegion) { +module.exports = function exampleInlineTagDef(parseArgString, createDocMessage) { return { name: 'example', description: @@ -24,14 +24,17 @@ module.exports = function exampleInlineTagDef(parseArgString, createDocMessage, var relativePath = unnamedArgs[0]; var regionName = tagArgs.region || (unnamedArgs.length > 1 ? unnamedArgs[1] : ''); if (regionName === '\'\'') regionName = ''; - var header = tagArgs.header || (unnamedArgs.length > 2 ? unnamedArgs.slice(2).join(' ') : null); + var header = tagArgs.header || (unnamedArgs.length > 2 ? unnamedArgs.slice(2).join(' ') : ''); var linenums = tagArgs.linenums; // var stylePattern = tagArgs.stylePattern; // TODO: not yet implemented here - const sourceCode = getExampleRegion(doc, relativePath, regionName); + if (!relativePath) { + throw new Error(createDocMessage( + `Missing required "path" on @${tagName} inline tag "{@${tagName} ${tagDescription}}".\n` + + 'Usage: {@example some/path [some-region [Some header [linenums="true|false"]]]}', doc)); + } - const attributes = []; - if (relativePath) attributes.push(` path="${relativePath}"`); + const attributes = [` path="${relativePath}"`]; if (regionName) attributes.push(` region="${regionName}"`); if (header) attributes.push(` header="${header}"`); if (linenums !== undefined) attributes.push(` linenums="${linenums}"`); @@ -40,8 +43,7 @@ module.exports = function exampleInlineTagDef(parseArgString, createDocMessage, // in order to throw an appropriate error in `renderExamples` later. if (tagArgs.title) attributes.push(` title="${tagArgs.title}"`); - return '\n' + sourceCode + '\n'; + return ''; } }; }; - diff --git a/aio/tools/transforms/examples-package/inline-tag-defs/example.spec.js b/aio/tools/transforms/examples-package/inline-tag-defs/example.spec.js index 296d809cc8..9421686d18 100644 --- a/aio/tools/transforms/examples-package/inline-tag-defs/example.spec.js +++ b/aio/tools/transforms/examples-package/inline-tag-defs/example.spec.js @@ -2,14 +2,12 @@ var testPackage = require('../../helpers/test-package'); var Dgeni = require('dgeni'); describe('example inline-tag-def', function() { - let injector, tag, collectExamples, exampleMap; + let tag; beforeEach(() => { const dgeni = new Dgeni([testPackage('examples-package', true)]); - injector = dgeni.configureInjector(); + const injector = dgeni.configureInjector(); tag = injector.get('exampleInlineTagDef'); - collectExamples = injector.get('collectExamples'); - exampleMap = injector.get('exampleMap'); }); it('should be available as a service', () => { @@ -20,62 +18,63 @@ describe('example inline-tag-def', function() { describe('handler', () => { let handler; - beforeEach(() => { - handler = tag.handler; - collectExamples.exampleFolders = ['examples']; - exampleMap['examples'] = { - 'test/url': { regions: { - '': { renderedContent: 'whole file' }, - 'region-1': { renderedContent: 'region 1 contents' } - } } - }; + beforeEach(() => handler = tag.handler); + + it('should throw if no path is specified add the specified path', () => { + expect(() => handler({}, 'example', '')).toThrowError( + 'Missing required "path" on @example inline tag "{@example }".\n' + + 'Usage: {@example some/path [some-region [Some header [linenums="true|false"]]]} - doc'); + + const tagDescription = 'region=\'region-1\' header="Some Header" linenums="true"'; + expect(() => handler({}, 'example', tagDescription)).toThrowError( + `Missing required "path" on @example inline tag "{@example ${tagDescription}}".\n` + + 'Usage: {@example some/path [some-region [Some header [linenums="true|false"]]]} - doc'); }); - it('should throw an error if there is no matching example', () => { - expect(function() { - handler({}, 'example', 'missing/uri'); - }).toThrowError(); - - expect(function() { - handler({}, 'example', 'test/url missing-region'); - }).toThrowError(); - }); - - it('should contain the whole contents from the example file if no region is specified', () => { - expect(handler({}, 'example', 'test/url')).toEqual('\nwhole file\n'); - }); - - it('should contain the region contents from the example file if a region is specified', () => { + it('should add a region if specified', () => { expect(handler({}, 'example', 'test/url region-1')).toEqual( - '\nregion 1 contents\n'); + ''); + + expect(handler({}, 'example', 'test/url -region=\'region-1\'')).toEqual( + ''); + + expect(handler({}, 'example', 'test/url region="region-1"')).toEqual( + ''); + }); + + it('should add no region if an empty (\'\') region is specified', () => { + expect(handler({}, 'example', 'test/url \'\'')).toEqual( + ''); + + expect(handler({}, 'example', 'test/url \'\' Some Header')).toEqual( + ''); }); it('should add a header if specified', () => { expect(handler({}, 'example', 'test/url region-1 \'Some Header\'')).toEqual( - '\nregion 1 contents\n'); + ''); + expect(handler({}, 'example', 'test/url region-1 Some Header')).toEqual( - '\nregion 1 contents\n'); + ''); + + expect(handler({}, 'example', 'test/url header="Some Header"')).toEqual( + ''); }); - it('should contain the whole contents from the example file if an empty ("") region is specified', () => { - expect(handler({}, 'example', 'test/url \'\'')).toEqual( - '\nwhole file\n'); - expect(handler({}, 'example', 'test/url \'\' Some Header')).toEqual( - '\nwhole file\n'); - }); - - it('should add in linenum attribute if specified', () => { + it('should add a linenum attribute if specified', () => { expect(handler({}, 'example', 'test/url --linenums=\'false\'')).toEqual( - '\nwhole file\n'); - expect(handler({}, 'example', 'test/url --linenums=\'true\'')).toEqual( - '\nwhole file\n'); - expect(handler({}, 'example', 'test/url --linenums=\'15\'')).toEqual( - '\nwhole file\n'); + ''); + + expect(handler({}, 'example', 'test/url -linenums=\'true\'')).toEqual( + ''); + + expect(handler({}, 'example', 'test/url linenums=\'15\'')).toEqual( + ''); }); it('should preserve the title if specified', () => { expect(handler({}, 'example', 'test/url title="Some Title"')).toEqual( - '\nwhole file\n'); + ''); }); }); }); diff --git a/aio/tools/transforms/examples-package/services/getExampleRegion.js b/aio/tools/transforms/examples-package/services/getExampleRegion.js index ebf09c241f..62defda9ba 100644 --- a/aio/tools/transforms/examples-package/services/getExampleRegion.js +++ b/aio/tools/transforms/examples-package/services/getExampleRegion.js @@ -15,7 +15,7 @@ module.exports = function getExampleRegion(exampleMap, createDocMessage, collect // If still no file then we error if (!exampleFile) { const gitIgnoreFile = collectExamples.isExampleIgnored(relativePath); - if( gitIgnoreFile) { + if (gitIgnoreFile) { const message = createDocMessage('Ignored example file... relativePath: "' + relativePath + '"', doc) + '\n' + 'This example file exists but has been ignored by a rule, in "' + gitIgnoreFile + '".'; throw new Error(message);