chore: ability to generate plunkers for API

gulpfile.js

@@ -38,15 +38,19 @@ var DOCS_PATH = path.join(PUBLIC_PATH, 'docs');
 
 var EXAMPLES_PATH = path.join(DOCS_PATH, '_examples');
 var EXAMPLES_PROTRACTOR_PATH = path.join(EXAMPLES_PATH, '_protractor');
+var ANGULAR_EXAMPLES_PATH = path.join(ANGULAR_PROJECT_PATH, 'modules/@angular/examples');
 var NOT_API_DOCS_GLOB = path.join(PUBLIC_PATH, './{docs/*/latest/!(api),!(docs)}/**/*.*');
 var RESOURCES_PATH = path.join(PUBLIC_PATH, 'resources');
 var LIVE_EXAMPLES_PATH = path.join(RESOURCES_PATH, 'live-examples');
+var API_LIVE_EXAMPLES_PATH = path.join(RESOURCES_PATH, 'api-live-examples');
 var STYLES_SOURCE_PATH = path.join(TOOLS_PATH, 'styles-builder/less');
 
 var docShredder = require(path.resolve(TOOLS_PATH, 'doc-shredder/doc-shredder'));
 var exampleZipper = require(path.resolve(TOOLS_PATH, '_example-zipper/exampleZipper'));
 var regularPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/regularPlunker'));
 var embeddedPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/embeddedPlunker'));
+var embeddedApiPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/embeddedApiPlunker'));
+var regularApiPlunker = require(path.resolve(TOOLS_PATH, 'plunker-builder/regularApiPlunker'));
 var fsUtils = require(path.resolve(TOOLS_PATH, 'fs-utils/fsUtils'));
 
 const isSilent = !!argv.silent;
@@ -611,7 +615,7 @@ gulp.task('build-docs', ['build-devguide-docs', 'build-api-docs', 'build-plunker
 // Stop zipping examples Feb 28, 2016
 //gulp.task('build-docs', ['build-devguide-docs', 'build-api-docs', 'build-plunkers', '_zip-examples']);
 
-gulp.task('build-api-docs', ['build-js-api-docs', 'build-ts-api-docs']
+gulp.task('build-api-docs', ['build-js-api-docs', 'build-ts-api-docs', 'build-plunkers-api']
     .concat(buildDartApiDocs ? ['build-dart-api-docs', 'build-dart-cheatsheet'] : []));
 
 gulp.task('build-devguide-docs', ['_shred-devguide-examples', '_shred-devguide-shared-jade'], function() {
@@ -636,6 +640,11 @@ gulp.task('build-plunkers', ['_copy-example-boilerplate'], function() {
   return embeddedPlunker.buildPlunkers(EXAMPLES_PATH, LIVE_EXAMPLES_PATH, { errFn: gutil.log, build: argv.build, targetSelf: argv.targetSelf });
 });
 
+gulp.task('build-plunkers-api', function() {
+  regularApiPlunker.buildPlunkers(ANGULAR_EXAMPLES_PATH, API_LIVE_EXAMPLES_PATH, { errFn: gutil.log, build: argv.build });
+  return embeddedApiPlunker.buildPlunkers(ANGULAR_EXAMPLES_PATH, API_LIVE_EXAMPLES_PATH, { errFn: gutil.log, build: argv.build });
+});
+
 gulp.task('build-dart-cheatsheet', [], function() {
   return buildDartCheatsheet();
 });
@@ -894,7 +903,7 @@ function harpCompile() {
   } else {
     gutil.log(`Harp full site compile, including API docs for all languages.`);
     if (skipLangs)
-      gutil.log(`Ignoring API docs skip set (${skipLangs}) because full ` + 
+      gutil.log(`Ignoring API docs skip set (${skipLangs}) because full ` +
       `site has not been built yet or some API HTML files are missing.`);
   }
 
@@ -1164,7 +1173,7 @@ function watchAndSync(options, cb) {
 
   // When using the --focus=name flag, only **/name/**/*.* example files and
   // **/name.jade files are watched. This is useful for performance reasons.
-  // Example: gulp serve-and-sync --focus=architecture 
+  // Example: gulp serve-and-sync --focus=architecture
   var focus = argv.focus;
 
   if (options.devGuide) {

public/resources/css/module/_api.scss

@@ -174,6 +174,14 @@ p {
   }
 }
 
+.api-live-example span {
+  vertical-align: middle;
+  cursor: pointer;
+}
+
+.api-live-example img {
+  vertical-align: middle;
+}
 
 @media screen and (max-width: 600px) {
   .docs-content {

public/resources/js/directives/live-example.js

@@ -21,6 +21,15 @@
 *
 *   <live-example embedded plnkr="minimal"></live-example>
 *   // ~/resources/live-examples/{chapter}/ts/minimal.eplnkr.html
+*
+*   <live-example api="core/animation/ts/dsl"></live-example>
+*   // ~/resources/api-live-examples/core/animation/ts/dsl/plnkr.html
+*
+*   <live-example api="core/animation/ts/dsl" embedded></live-example>
+*   // ~/resources/api-live-examples/core/animation/ts/dsl/eplnkr.html
+*
+*   <live-example api="core/animation/ts/dsl" noimg></live-example>
+*   // ~/resources/api-live-examples/core/animation/ts/dsl/plnkr.html
 */
 angularIO.directive('liveExample', ['$location', function ($location) {
 
@@ -30,7 +39,18 @@ angularIO.directive('liveExample', ['$location', function ($location) {
     return '<a' + attr +  '>' + text + '</a>';
   }
 
-  function span(text) { return '<span>' + text + '</span>'; }
+  function embeddedNoImgTemplate(src) {
+    return '<div ng-if="embeddedShow">' +
+        '<div class="api-live-example" ng-click="toggleEmbedded()" ng-if="embeddedShow">' +
+          '<img src="/resources/images/icons/ic_keyboard_arrow_down_black_24px.svg"><span>Live example</span>' +
+        '</div>' +
+        '<iframe frameborder="0" width="100%" height="100%" src="' + src + '"></iframe>' +
+      '</div>' +
+      '<div class="api-live-example" ng-click="toggleEmbedded()" ng-if="!embeddedShow">' +
+        '<img src="/resources/images/icons/ic_keyboard_arrow_right_black_24px.svg"><span>Live example</span>' +
+      '</div>'
+
+  }
 
   function embeddedTemplate(src, img) {
     return '<div ng-if="embeddedShow">' +
@@ -39,6 +59,24 @@ angularIO.directive('liveExample', ['$location', function ($location) {
       '<img ng-click="toggleEmbedded()" ng-if="!embeddedShow" src="' + img + '" alt="plunker">';
   }
 
+  function getHref(langOrApi, example, plnkr) {
+    var href;
+    switch (langOrApi) {
+      case 'ts':
+      case 'js':
+        href = '/resources/live-examples/' + example + '/' + langOrApi + '/' + plnkr + '.html';
+        break;
+      case 'dart':
+        href = 'http://angular-examples.github.io/' + example;
+        break;
+      case 'api':
+        href = '/resources/api-live-examples/' + example + '/' + plnkr + '.html';
+    }
+    return href;
+  }
+
+  function span(text) { return '<span>' + text + '</span>'; }
+
   return {
     restrict: 'E',
     scope: true,
@@ -47,35 +85,41 @@ angularIO.directive('liveExample', ['$location', function ($location) {
       var ex = attrs.name || NgIoUtil.getExampleName($location);
       var embedded = attrs.hasOwnProperty('embedded');
       var plnkr = embedded ? 'eplnkr' : 'plnkr';
-      var href, template;
+      var href, template, exLang;
       var imageBase  = '/resources/images/';
       var defaultImg = 'plunker/placeholder.png';
-
+      var noImg = angular.isDefined(attrs.noimg);
+      var isApi = !!attrs.api;
+      console.log(noImg);
       if (attrs.plnkr) {
         plnkr = attrs.plnkr + '.' + plnkr;
       }
 
+      if (isApi) {
+        ex = attrs.api;
+        exLang = 'api';
+      } else {
+        exLang = isForDart ? 'dart' : isForJs ? 'js' : 'ts';
+      }
+
       var isForDart = attrs.lang === 'dart' || NgIoUtil.isDoc($location, 'dart');
       var isForJs = attrs.lang === 'js' || NgIoUtil.isDoc($location, 'js');
-      var exLang = isForDart ? 'dart' : isForJs ? 'js' : 'ts';
 
       if (embedded && !isForDart) {
-        href = '/resources/live-examples/' + ex + '/' + exLang + '/' + plnkr + '.html';
+        href = getHref(exLang, ex, plnkr);
         img = imageBase + (attrs.img || defaultImg);
-        template = embeddedTemplate(href, img);
+        template = noImg ? embeddedNoImgTemplate(href) : embeddedTemplate(href, img);
       } else {
-        var href = isForDart
-          ? 'http://angular-examples.github.io/' + ex
-          : '/resources/live-examples/' + ex + '/' + exLang + '/' + plnkr + '.html'
+        href = getHref(exLang, ex, plnkr);
 
         // Link to live example.
-        var template = a(text, { href: href, target: '_blank' });
+        template = a(text, { href: href, target: '_blank' });
 
         // The hosted example and sources are in different locations for Dart.
         // Also show link to sources for Dart, unless noSource is specified.
         if (isForDart && !attrs.hasOwnProperty('nosource')) {
           var srcText = attrs.srcText || 'view source';
-          var srcHref = 'http://github.com/angular-examples/' + ex;
+          href = getHref('dart', ex);
           template = span(template + ' (' + a(srcText, { href: srcHref, target: '_blank' }) + ')');
         }
       }

tools/api-builder/angular.io-package/rendering/indentForMarkdown.js

@@ -59,4 +59,4 @@ module.exports = function(encodeCodeBlock) {
     return str;
   };
 
-};
+};

tools/api-builder/links-package/index.js

@@ -6,6 +6,7 @@ module.exports = new Package('links', [])
 .factory(require('./inline-tag-defs/linkDocs'))
 .factory(require('./inline-tag-defs/example'))
 .factory(require('./inline-tag-defs/exampleTabs'))
+.factory(require('./inline-tag-defs/liveExample'))
 .factory(require('dgeni-packages/links/services/getAliases'))
 .factory(require('dgeni-packages/links/services/getDocFromAlias'))
 .factory(require('./services/getLinkInfo'))
@@ -14,11 +15,12 @@ module.exports = new Package('links', [])
 .factory(require('./services/deprecatedDocsLinkDisambiguator'))
 .factory(require('./services/getApiFragmentFileName'))
 
-.config(function(inlineTagProcessor, linkInlineTagDef, linkDocsInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef) {
+.config(function(inlineTagProcessor, linkInlineTagDef, linkDocsInlineTagDef, exampleInlineTagDef, exampleTabsInlineTagDef, liveExampleInlineTagDef) {
   inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef);
   inlineTagProcessor.inlineTagDefinitions.push(linkDocsInlineTagDef);
   inlineTagProcessor.inlineTagDefinitions.push(exampleInlineTagDef);
   inlineTagProcessor.inlineTagDefinitions.push(exampleTabsInlineTagDef);
+  inlineTagProcessor.inlineTagDefinitions.push(liveExampleInlineTagDef);
 })
 
 .config(function(getLinkInfo, moduleScopeLinkDisambiguator, deprecatedDocsLinkDisambiguator) {

tools/api-builder/links-package/inline-tag-defs/liveExample.js

@@ -0,0 +1,39 @@
+var path = require('canonical-path');
+var fs = require("fs");
+
+/**
+ * @dgService liveExampleInlineTagDef
+ * @description
+ * Process inline liveExample tags (of the form {@liveExample demo-path embedded }),
+ * replacing them with a <live-example> directive.
+ * Examples:
+ * {@liveExample core/animation/ts/dsl }
+ * {@liveExample core/di/ts/contentChildren embedded }
+ * @kind function
+ */
+module.exports = function liveExampleInlineTagDef(getLinkInfo, parseArgString, getApiFragmentFileName, createDocMessage, log) {
+  return {
+    name: 'liveExample',
+    description: 'Process inline liveExample tags (of the form {@liveExample demo-path embedded }), replacing them with <live-example>',
+    handler: function(doc, tagName, tagDescription) {
+
+      var tagArgs = parseArgString(tagDescription);
+      var unnamedArgs = tagArgs._;
+      var relativePath = unnamedArgs[0] !== 'embedded' ? unnamedArgs[0] : unnamedArgs[1];
+      var embedded = unnamedArgs.indexOf('embedded') >= 0 ? 'embedded' : '';
+      var imgPath = tagArgs.img;
+
+      // check if fragment file actually exists.
+      var apiPlunkerFile = getApiPlunkerFile(relativePath);
+      if ( !fs.existsSync(apiPlunkerFile)) {
+        log.warn(createDocMessage(`Invalid example (unable to locate plunker file: ${apiPlunkerFile}`));
+      }
+
+      return [ `<live-example api="${relativePath}" ${embedded} ${imgPath ? `img="${imgPath}"` : 'noimg'}></live-example>` ];
+    }
+  };
+};
+
+function getApiPlunkerFile(relativePath) {
+  return path.join('/resources/api-live-examples', `${relativePath}/plnkr.html`);
+}

tools/plunker-builder/boilerplate/index.html

@@ -0,0 +1,30 @@
+<!DOCTYPE html>
+<html>
+ <head>
+    <meta charset="UTF-8">
+    <title>Animations</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <!-- Polyfill for Web Animations -->
+    <script src="https://unpkg.com/[email protected]"></script>
+
+    <!-- Polyfill(s) for older browsers -->
+    <script src="https://unpkg.com/core-js/client/shim.min.js"></script>
+
+    <script src="https://unpkg.com/[email protected]?main=browser"></script>
+    <script src="https://unpkg.com/[email protected]"></script>
+    <script src="https://unpkg.com/[email protected]/dist/system.src.js"></script>
+
+    <script src="systemjs.config.js"></script>
+    <script>
+      System.import('app').catch(function(err){ console.error(err); });
+    </script>
+  </head>
+
+  <body>
+    <example-app>
+      Loading...
+    </example-app>
+  </body>
+
+</html>

tools/plunker-builder/boilerplate/main.ts

@@ -0,0 +1,5 @@
+import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
+
+import { AppModule } from './module.ts';
+
+platformBrowserDynamic().bootstrapModule(AppModule);