iSharkFly-Docs
/
angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

build(docs-infra): only render code example content in one place (#26514) 

PR Close #26514
This commit is contained in:
George Kalpakas 2018-10-18 14:32:32 +03:00 committed by Miško Hevery
parent 0add00a743
commit 7bad1d356d
3 changed files with 54 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
aio/tools/transforms/examples-package/inline-tag-defs/example.js
View File

@ -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 '<code-example' + attributes.join('') + '>\n' + sourceCode + '\n</code-example>';
return '<code-example' + attributes.join('') + '></code-example>';
}
};
};

89
aio/tools/transforms/examples-package/inline-tag-defs/example.spec.js
View File

@ -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('<code-example path="test/url">\nwhole file\n</code-example>');
});
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(
'<code-example path="test/url" region="region-1">\nregion 1 contents\n</code-example>');
'<code-example path="test/url" region="region-1"></code-example>');
expect(handler({}, 'example', 'test/url -region=\'region-1\'')).toEqual(
'<code-example path="test/url" region="region-1"></code-example>');
expect(handler({}, 'example', 'test/url region="region-1"')).toEqual(
'<code-example path="test/url" region="region-1"></code-example>');
});
it('should add no region if an empty (\'\') region is specified', () => {
expect(handler({}, 'example', 'test/url \'\'')).toEqual(
'<code-example path="test/url"></code-example>');
expect(handler({}, 'example', 'test/url \'\' Some Header')).toEqual(
'<code-example path="test/url" header="Some Header"></code-example>');
});
it('should add a header if specified', () => {
expect(handler({}, 'example', 'test/url region-1 \'Some Header\'')).toEqual(
'<code-example path="test/url" region="region-1" header="Some Header">\nregion 1 contents\n</code-example>');
'<code-example path="test/url" region="region-1" header="Some Header"></code-example>');
expect(handler({}, 'example', 'test/url region-1 Some Header')).toEqual(
'<code-example path="test/url" region="region-1" header="Some Header">\nregion 1 contents\n</code-example>');
'<code-example path="test/url" region="region-1" header="Some Header"></code-example>');
expect(handler({}, 'example', 'test/url header="Some Header"')).toEqual(
'<code-example path="test/url" header="Some Header"></code-example>');
});
it('should contain the whole contents from the example file if an empty ("") region is specified', () => {
expect(handler({}, 'example', 'test/url \'\'')).toEqual(
'<code-example path="test/url">\nwhole file\n</code-example>');
expect(handler({}, 'example', 'test/url \'\' Some Header')).toEqual(
'<code-example path="test/url" header="Some Header">\nwhole file\n</code-example>');
});
it('should add in linenum attribute if specified', () => {
it('should add a linenum attribute if specified', () => {
expect(handler({}, 'example', 'test/url --linenums=\'false\'')).toEqual(
'<code-example path="test/url" linenums="false">\nwhole file\n</code-example>');
expect(handler({}, 'example', 'test/url --linenums=\'true\'')).toEqual(
'<code-example path="test/url" linenums="true">\nwhole file\n</code-example>');
expect(handler({}, 'example', 'test/url --linenums=\'15\'')).toEqual(
'<code-example path="test/url" linenums="15">\nwhole file\n</code-example>');
'<code-example path="test/url" linenums="false"></code-example>');
expect(handler({}, 'example', 'test/url -linenums=\'true\'')).toEqual(
'<code-example path="test/url" linenums="true"></code-example>');
expect(handler({}, 'example', 'test/url linenums=\'15\'')).toEqual(
'<code-example path="test/url" linenums="15"></code-example>');
});
it('should preserve the title if specified', () => {
expect(handler({}, 'example', 'test/url title="Some Title"')).toEqual(
'<code-example path="test/url" title="Some Title">\nwhole file\n</code-example>');
'<code-example path="test/url" title="Some Title"></code-example>');
});
});
});

2
aio/tools/transforms/examples-package/services/getExampleRegion.js
View File

@ -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);