build(aio): output `{@example}` tags as `<code-example>` elements (#15382)

aio/e2e/app.e2e-spec.ts

@@ -31,7 +31,12 @@ describe('site App', function() {
     expect(page.getDocViewerText()).toMatch(/Tutorial: Tour of Heroes/i);
   });
 
-  it('should convert a doc with a code-example');
+  it('should render `{@example}` dgeni tags as `<code-example>` elements with HTML escaped content', () => {
+    page.navigateTo('guide/component-styles');
+    const codeExample = element.all(by.css('code-example')).first();
+    expect(page.getInnerHtml(codeExample))
+        .toContain('@Component({\n  selector: \'hero-app\',\n  template: `\n    &lt;h1&gt;Tour of Heroes&lt;/h1&gt;');
+  });
 
   describe('api-docs', () => {
     it('should show a link to github', () => {

aio/e2e/app.po.ts

@@ -28,6 +28,12 @@ export class SitePage {
     return this.docViewer.getText();
   }
 
+  getInnerHtml(element) {
+    // `getInnerHtml` was removed from webDriver and this is the workaround.
+    // See https://github.com/angular/protractor/blob/master/CHANGELOG.md#breaking-changes
+    return browser.executeScript('return arguments[0].innerHTML;', element);
+  }
+
   /**
    * Replace the ambient Google Analytics tracker with homebrew spy
    * don't send commands to GA during e2e testing!

aio/transforms/examples-package/inline-tag-defs/example.js

@@ -28,40 +28,48 @@ module.exports = function exampleInlineTagDef(
       var unnamedArgs = tagArgs._;
       var relativePath = unnamedArgs[0];
       var regionName = tagArgs.region || (unnamedArgs.length > 1 ? unnamedArgs[1] : '');
-      var title = tagArgs.title || (unnamedArgs.length > 2 ? unnamedArgs[2] : null);
+      if (regionName === '\'\'') regionName = '';
+      var title = tagArgs.title || (unnamedArgs.length > 2 ? unnamedArgs.slice(2).join(' ') : null);
+      var linenums = tagArgs.linenums;
       var stylePattern = tagArgs.stylePattern;  // TODO: not yet implemented here
 
+      const sourceCode = getExampleRegion();
+
+      const attributes = [];
+      if (title) attributes.push(` title="${title}"`);
+      if (linenums !== undefined) attributes.push(` linenums="${linenums}"`);
+
+      return '<code-example' + attributes.join('') + '>\n' + sourceCode + '\n</code-example>';
+
+
+      function getExampleRegion() {
         // Find the example in the folders
         var exampleFile;
         // Try an "annotated" version first
-      EXAMPLES_FOLDERS.some(
-          EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath + '.annotated']; });
+        EXAMPLES_FOLDERS.some(EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath + '.annotated']; });
 
         // If no annotated version is available then try the actual file
         if (!exampleFile) {
-        EXAMPLES_FOLDERS.some(
-            EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath]; });
+          EXAMPLES_FOLDERS.some(EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath]; });
         }
 
         // If still no file then we error
         if (!exampleFile) {
-        log.error(
-            createDocMessage('Missing example file... relativePath: "' + relativePath + '".', doc));
+          log.error(createDocMessage('Missing example file... relativePath: "' + relativePath + '".', doc));
           log.error('Example files can be found in: ' + EXAMPLES_FOLDERS.join(', '));
           return '';
         }
 
-      var sourceCode = exampleFile.regions[regionName];
-      if (!sourceCode) {
-        log.error(createDocMessage(
-            'Missing example region... relativePath: "' + relativePath + '", region: "' +
-                regionName + '".',
-            doc));
+        var sourceCodeDoc = exampleFile.regions[regionName];
+        if (!sourceCodeDoc) {
+          log.error(createDocMessage('Missing example region... relativePath: "' + relativePath + '", region: "' + regionName + '".', doc));
           log.error('Regions available are:', Object.keys[exampleFile.regions]);
           return '';
         }
 
-      return sourceCode.renderedContent;
+        return sourceCodeDoc.renderedContent;
+      }
     }
   };
 };
+

aio/transforms/examples-package/inline-tag-defs/example.spec.js

@@ -0,0 +1,63 @@
+var testPackage = require('../../helpers/test-package');
+var Dgeni = require('dgeni');
+
+describe('example inline-tag-def', function() {
+  let injector, tag, collectExamples, exampleMap;
+
+  beforeEach(() => {
+    const dgeni = new Dgeni([testPackage('examples-package', true)]);
+    injector = dgeni.configureInjector();
+    tag = injector.get('exampleInlineTagDef');
+    collectExamples = injector.get('collectExamples');
+    exampleMap = injector.get('exampleMap');
+  });
+
+  it('should be available as a service', () => {
+    expect(tag).toBeDefined();
+    expect(tag.name).toEqual('example');
+  });
+
+  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' }
+        } }
+      };
+    });
+
+    it('should return a <code-example> tag', () => {
+      expect(handler({}, 'example', 'some/uri')).toEqual('<code-example>\n\n</code-example>');
+    });
+
+    it('should contain the whole contents from the example file if no region is specified', () => {
+      expect(handler({}, 'example', 'test/url')).toEqual('<code-example>\nwhole file\n</code-example>');
+    });
+
+    it('should contain the region contents from the example file if a region is specified', () => {
+      expect(handler({}, 'example', 'test/url region-1')).toEqual('<code-example>\nregion 1 contents\n</code-example>');
+    });
+
+    it('should add a title if specified', () => {
+      expect(handler({}, 'example', 'test/url region-1 \'Some Title\'')).toEqual('<code-example title="Some Title">\nregion 1 contents\n</code-example>');
+      expect(handler({}, 'example', 'test/url region-1 Some Title')).toEqual('<code-example title="Some Title">\nregion 1 contents\n</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>\nwhole file\n</code-example>');
+      expect(handler({}, 'example', 'test/url \'\' Some Title')).toEqual('<code-example title="Some Title">\nwhole file\n</code-example>');
+    });
+
+    it('should add in linenum attribute if specified', () => {
+      expect(handler({}, 'example', 'test/url --linenums=\'false\'')).toEqual('<code-example linenums="false">\nwhole file\n</code-example>');
+      expect(handler({}, 'example', 'test/url --linenums=\'true\'')).toEqual('<code-example linenums="true">\nwhole file\n</code-example>');
+      expect(handler({}, 'example', 'test/url --linenums=\'15\'')).toEqual('<code-example linenums="15">\nwhole file\n</code-example>');
+    });
+  });
+});
+

aio/transforms/examples-package/services/parseArgString.js

@@ -39,7 +39,10 @@ module.exports = function parseArgString() {
         } else {
           if (arg.substr(arg.length - 1) === '=') {
             key = arg.substr(0, arg.length - 1);
-            // remove leading '-' if it exists.
+            // remove leading '-' (or '--') if it exists.
+            if (key.substr(0, 1) == '-') {
+              key = key.substr(1);
+            }
             if (key.substr(0, 1) == '-') {
               key = key.substr(1);
             }

aio/transforms/templates/example-region.template.html

@@ -1,7 +1 @@
-<div class="code-example">
-{% marked %}
-```
-{$ doc.contents $}
-```
-{% endmarked %}
-</div>
+{$ doc.contents | escape $}