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.

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,6 +18,7 @@ module.exports = function renderExamples(getExampleRegion) {
             (original, openingTag, attributes, closingTag) => {
               const attrMap = parseAttributes(attributes);
               if (attrMap.path) {
+                try {
                   if (closingTag !== openingTag) {
                     // The markdown renderer will wrap what it thinks is a paragraph in `<p>` and `</p>` tags.
                     // If you do not leave a blank line between a paragraph of text and a `<code-example>` then
@@ -45,6 +47,12 @@ module.exports = function renderExamples(getExampleRegion) {
                   // 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;
+                  }
+                }
               }
               // No path attribute so just ignore this one
               return original;
@@ -54,4 +62,3 @@ module.exports = function renderExamples(getExampleRegion) {
     }
   };
 };
-

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