diff --git a/aio/tools/transforms/examples-package/processors/render-examples.js b/aio/tools/transforms/examples-package/processors/render-examples.js index ac777cf9d0..b90d5763f1 100644 --- a/aio/tools/transforms/examples-package/processors/render-examples.js +++ b/aio/tools/transforms/examples-package/processors/render-examples.js @@ -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. * 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 { $runAfter: ['docs-rendered'], $runBefore: ['writing-files'], + ignoreBrokenExamples: false, $process: function(docs) { docs.forEach(doc => { if (doc.renderedContent) { @@ -17,34 +18,41 @@ module.exports = function renderExamples(getExampleRegion) { (original, openingTag, attributes, closingTag) => { const attrMap = parseAttributes(attributes); if (attrMap.path) { - if (closingTag !== openingTag) { - // The markdown renderer will wrap what it thinks is a paragraph in `

` and `

` tags. - // If you do not leave a blank line between a paragraph of text and a `` then - // the markdown renderer may add a paragraph marker "in-between" the opening and closing - // tags of the code-example. For example: - // - // ``` - // Some paragraph - // - // - // - // ``` - // - // will be rendered as: - // - // ``` - //

Some paragraph - // - //

- //
- // ``` - throw new Error( - 'Badly formed example: ' + original + ' - closing tag does not match opening tag.\n' + - ' - Perhaps you forgot to put a blank line before the example?'); + try { + if (closingTag !== openingTag) { + // The markdown renderer will wrap what it thinks is a paragraph in `

` and `

` tags. + // If you do not leave a blank line between a paragraph of text and a `` then + // the markdown renderer may add a paragraph marker "in-between" the opening and closing + // tags of the code-example. For example: + // + // ``` + // Some paragraph + // + // + // + // ``` + // + // will be rendered as: + // + // ``` + //

Some paragraph + // + //

+ //
+ // ``` + throw new Error( + '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`; + } 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`; } // No path attribute so just ignore this one return original; @@ -54,4 +62,3 @@ module.exports = function renderExamples(getExampleRegion) { } }; }; - diff --git a/aio/tools/transforms/examples-package/processors/render-examples.spec.js b/aio/tools/transforms/examples-package/processors/render-examples.spec.js index 362d8406f5..2fdf0bab9b 100644 --- a/aio/tools/transforms/examples-package/processors/render-examples.spec.js +++ b/aio/tools/transforms/examples-package/processors/render-examples.spec.js @@ -2,7 +2,7 @@ var testPackage = require('../../helpers/test-package'); var Dgeni = require('dgeni'); describe('renderExamples processor', () => { - var injector, processor, exampleMap, collectExamples; + var injector, processor, exampleMap, collectExamples, log; beforeEach(function() { const dgeni = new Dgeni([testPackage('examples-package', true)]); @@ -12,6 +12,7 @@ describe('renderExamples processor', () => { processor = injector.get('renderExamples'); collectExamples = injector.get('collectExamples'); exampleMap = injector.get('exampleMap'); + log = injector.get('log'); collectExamples.exampleFolders = ['examples']; exampleMap['examples'] = { @@ -97,6 +98,25 @@ describe('renderExamples processor', () => { 'Badly formed example: <' + CODE_TAG + ' path="test/url">

- closing tag does not match opening tag.\n' + ' - 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">

`}, + { renderedContent: `<${CODE_TAG} path="test/url" region="missing">`}, + { renderedContent: `<${CODE_TAG} path="missing/url">`} + ]; + expect(() => processor.$process(docs)).not.toThrow(); + expect(log.warn).toHaveBeenCalledWith( + 'Badly formed example: <' + CODE_TAG + ' path="test/url">

- 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'); + }); }) ); });