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

build(aio): allow render-examples to complete even if examples are broken 

By setting `renderExamples.ignoreBrokenExamples = true` the doc-gen will
not fail if there is something wrong with an example. Instead it will
just log a warning.
This commit is contained in:
Peter Bacon Darwin 2017-10-30 21:25:48 +00:00 committed by Victor Berchet
parent feae55b264
commit 3a03ff6b2d
2 changed files with 57 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
aio/tools/transforms/examples-package/processors/render-examples.js
View File

@ -4,10 +4,11 @@ const { parseAttributes, renderAttributes } = require('../../helpers/utils');
* Search the renderedContent looking for code examples that have a path (and optionally a region) attribute. * Search the renderedContent looking for code examples that have a path (and optionally a region) attribute.
* When they are found replace their content with the appropriate doc-region parsed previously from an example file. * When they are found replace their content with the appropriate doc-region parsed previously from an example file.
*/ */
module.exports = function renderExamples(getExampleRegion) { module.exports = function renderExamples(getExampleRegion, log, createDocMessage) {
return { return {
$runAfter: ['docs-rendered'], $runAfter: ['docs-rendered'],
$runBefore: ['writing-files'], $runBefore: ['writing-files'],
ignoreBrokenExamples: false,
$process: function(docs) { $process: function(docs) {
docs.forEach(doc => { docs.forEach(doc => {
if (doc.renderedContent) { if (doc.renderedContent) {
@ -17,34 +18,41 @@ module.exports = function renderExamples(getExampleRegion) {
(original, openingTag, attributes, closingTag) => { (original, openingTag, attributes, closingTag) => {
const attrMap = parseAttributes(attributes); const attrMap = parseAttributes(attributes);
if (attrMap.path) { if (attrMap.path) {
if (closingTag !== openingTag) { try {
// The markdown renderer will wrap what it thinks is a paragraph in `<p>` and `</p>` tags. if (closingTag !== openingTag) {
// If you do not leave a blank line between a paragraph of text and a `<code-example>` then // The markdown renderer will wrap what it thinks is a paragraph in `<p>` and `</p>` tags.
// the markdown renderer may add a paragraph marker "in-between" the opening and closing // If you do not leave a blank line between a paragraph of text and a `<code-example>` then
// tags of the code-example. For example: // the markdown renderer may add a paragraph marker "in-between" the opening and closing
// // tags of the code-example. For example:
// ``` //
// Some paragraph // ```
// <code-example path="..."> // Some paragraph
// // <code-example path="...">
// </code-example> //
// ``` // </code-example>
// // ```
// will be rendered as: //
// // will be rendered as:
// ``` //
// <p>Some paragraph // ```
// <code-example path="..."> // <p>Some paragraph
// </p> // <code-example path="...">
// </code-example> // </p>
// ``` // </code-example>
throw new Error( // ```
'Badly formed example: ' + original + ' - closing tag does not match opening tag.\n' + throw new Error(
' - Perhaps you forgot to put a blank line before the example?'); 'Badly formed example: ' + original + ' - closing tag does not match opening tag.\n' +
' - Perhaps you forgot to put a blank line before the example?');
}
// We found a path attribute so look up the example and rebuild the HTML
const exampleContent = getExampleRegion(doc, attrMap.path, attrMap.region);
return `<${openingTag}${renderAttributes(attrMap)}>\n${exampleContent}\n</${openingTag}>`;
} catch(e) {
log.warn(createDocMessage(e.message, doc));
if (!this.ignoreBrokenExamples) {
throw e;
}
} }
// We found a path attribute so look up the example and rebuild the HTML
const exampleContent = getExampleRegion(doc, attrMap.path, attrMap.region);
return `<${openingTag}${renderAttributes(attrMap)}>\n${exampleContent}\n</${openingTag}>`;
} }
// No path attribute so just ignore this one // No path attribute so just ignore this one
return original; return original;
@ -54,4 +62,3 @@ module.exports = function renderExamples(getExampleRegion) {
} }
}; };
}; };

22
aio/tools/transforms/examples-package/processors/render-examples.spec.js
View File

@ -2,7 +2,7 @@ var testPackage = require('../../helpers/test-package');
var Dgeni = require('dgeni'); var Dgeni = require('dgeni');
describe('renderExamples processor', () => { describe('renderExamples processor', () => {
var injector, processor, exampleMap, collectExamples; var injector, processor, exampleMap, collectExamples, log;
beforeEach(function() { beforeEach(function() {
const dgeni = new Dgeni([testPackage('examples-package', true)]); const dgeni = new Dgeni([testPackage('examples-package', true)]);
@ -12,6 +12,7 @@ describe('renderExamples processor', () => {
processor = injector.get('renderExamples'); processor = injector.get('renderExamples');
collectExamples = injector.get('collectExamples'); collectExamples = injector.get('collectExamples');
exampleMap = injector.get('exampleMap'); exampleMap = injector.get('exampleMap');
log = injector.get('log');
collectExamples.exampleFolders = ['examples']; collectExamples.exampleFolders = ['examples'];
exampleMap['examples'] = { exampleMap['examples'] = {
@ -97,6 +98,25 @@ describe('renderExamples processor', () => {
'Badly formed example: <' + CODE_TAG + ' path="test/url"></p> - closing tag does not match opening tag.\n' + 'Badly formed example: <' + CODE_TAG + ' path="test/url"></p> - closing tag does not match opening tag.\n' +
' - Perhaps you forgot to put a blank line before the example?'); ' - Perhaps you forgot to put a blank line before the example?');
}); });
it('should not throw if `ignoreBrokenExamples` is set to true', () => {
processor.ignoreBrokenExamples = true;
const docs = [
{ renderedContent: `<${CODE_TAG} path="test/url"></p></${CODE_TAG}>`},
{ renderedContent: `<${CODE_TAG} path="test/url" region="missing"></${CODE_TAG}>`},
{ renderedContent: `<${CODE_TAG} path="missing/url"></${CODE_TAG}>`}
];
expect(() => processor.$process(docs)).not.toThrow();
expect(log.warn).toHaveBeenCalledWith(
'Badly formed example: <' + CODE_TAG + ' path="test/url"></p> - closing tag does not match opening tag.\n' +
' - Perhaps you forgot to put a blank line before the example? - doc');
expect(log.warn).toHaveBeenCalledWith(
'Missing example region... relativePath: "test/url", region: "missing". - doc\n' +
'Regions available are: "", "region-1" - doc');
expect(log.warn).toHaveBeenCalledWith(
'Missing example file... relativePath: "missing/url". - doc\n' +
'Example files can be found in the following relative paths: "examples" - doc');
});
}) })
); );
}); });