angular · petebacondarwin · Dec 8, 2015 · Dec 8, 2015 · Dec 9, 2015
diff --git a/gulpfile.js b/gulpfile.js
@@ -83,7 +83,7 @@ gulp.task('build-and-serve', ['build-docs'], function (cb) {
 
 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-dart-cheatsheet']);
 
 gulp.task('build-devguide-docs', ['_shred-devguide-examples'], function() {
   return buildShredMaps(true);
@@ -101,6 +101,10 @@ gulp.task('build-plunkers', function() {
   return plunkerBuilder.buildPlunkers(EXAMPLES_PATH, LIVE_EXAMPLES_PATH, { errFn: gutil.log });
 });
 
+gulp.task('build-dart-cheatsheet', [], function() {
+  return buildApiDocs('dart');
+});
+
 gulp.task('git-changed-examples', ['_shred-devguide-examples'], function(){
   var after, sha, messageSuffix;
   if (argv.after) {
@@ -290,15 +294,21 @@ function devGuideExamplesWatch(shredOptions, postShredAction) {
 
 // Generate the API docs for the specified language, if not specified then it defaults to ts
 function buildApiDocs(targetLanguage) {
-  var ALLOWED_LANGUAGES = ['ts', 'js'];
+  var ALLOWED_LANGUAGES = ['ts', 'js', 'dart'];
+  var GENERATE_API_LANGUAGES = ['ts', 'js'];
   checkAngularProjectPath();
   try {
     // Build a specialized package to generate different versions of the API docs
     var package = new Package('apiDocs', [require(path.resolve(TOOLS_PATH, 'api-builder/angular.io-package'))]);
-    package.config(function(targetEnvironments, writeFilesProcessor) {
+    package.config(function(targetEnvironments, writeFilesProcessor, readTypeScriptModules) {
       ALLOWED_LANGUAGES.forEach(function(target) { targetEnvironments.addAllowed(target); });
       if (targetLanguage) {
         targetEnvironments.activate(targetLanguage);
+
+        if (GENERATE_API_LANGUAGES.indexOf(targetLanguage) === -1) {
+          // Don't read TypeScript modules if we are not generating API docs - Dart I am looking at you!
+          readTypeScriptModules.$enabled = false;
+        }
         writeFilesProcessor.outputFolder  = targetLanguage + '/latest/api';
       }
     });

diff --git a/public/_includes/_scripts-include.jade b/public/_includes/_scripts-include.jade
@@ -16,6 +16,7 @@ script(src="https://ajax.googleapis.com/ajax/libs/angular_material/0.8.3/angular
 <!-- Angular.io Site JS -->
 script(src="/resources/js/site.js")
 script(src="/resources/js/controllers/app-controller.js")
+script(src="/resources/js/directives/cheatsheet.js")
 script(src="/resources/js/directives/bio.js")
 script(src="/resources/js/directives/code.js")
 script(src="/resources/js/directives/code-tabs.js")

diff --git a/public/docs/dart/latest/guide/_data.json b/public/docs/dart/latest/guide/_data.json
@@ -5,6 +5,10 @@
     "title": "Step By Step Guide"
   },
 
+  "cheatsheet": {
+    "title": "Angular Cheat Sheet"
+  },
+
   "setup": {
     "title": "Getting Started"
   },

diff --git a/public/docs/dart/latest/guide/cheatsheet.jade b/public/docs/dart/latest/guide/cheatsheet.jade
@@ -0,0 +1,9 @@
+.banner
+  p.text-body This cheat sheet is provisional and may change. Angular 2 is currently in Developer Preview.
+
+article(class="l-content-small grid-fluid docs-content")
+  .cheatsheet
+    h2 Angular for Dart Cheat Sheet (v2.0.0-alpha.44)
+    br
+    br
+    ngio-cheatsheet(src='./cheatsheet.json')
diff --git a/public/docs/js/latest/guide/_data.json b/public/docs/js/latest/guide/_data.json
@@ -5,6 +5,10 @@
     "title": "Developer Guide"
   },
 
+  "cheatsheet": {
+    "title": "Angular Cheat Sheet"
+  },
+
   "displaying-data": {
     "title": "Displaying Data",
     "intro": "Displaying data is job number one for any good application. In Angular, you bind data to elements in HTML templates and Angular automatically updates the UI as data changes."

diff --git a/public/docs/js/latest/guide/cheatsheet.jade b/public/docs/js/latest/guide/cheatsheet.jade
@@ -0,0 +1,9 @@
+.banner
+  p.text-body This cheat sheet is provisional and may change. Angular 2 is currently in Developer Preview.
+
+article(class="l-content-small grid-fluid docs-content")
+  .cheatsheet
+    h2 Angular for JavaScript Cheat Sheet (v2.0.0-alpha.44)
+    br
+    br
+    ngio-cheatsheet(src='./cheatsheet.json')
diff --git a/public/docs/ts/latest/guide/cheatsheet.jade b/public/docs/ts/latest/guide/cheatsheet.jade
@@ -16,11 +16,4 @@ article(class="l-content-small grid-fluid docs-content")
     br
     br
 
-    table(ng-repeat='section in appCtrl.cheatsheet' ng-cloak)
-      tr
-        th {{section.name}}
-        th(ng-bind-html="appCtrl.getSafeHtml(section.description)")
-      tr(ng-repeat='child in section.items')
-        td
-          code(bold='child.bold',ng-compile) {{child.syntax}}
-        td(ng-bind-html="appCtrl.getSafeHtml(child.description)")
+    ngio-cheatsheet(src='./cheatsheet.json')
diff --git a/public/resources/js/controllers/app-controller.js b/public/resources/js/controllers/app-controller.js
@@ -31,10 +31,6 @@ angularIO.controller('AppCtrl', ['$mdDialog', '$timeout', '$http', '$sce', funct
     vm.apiList = response.data;
   });
 
-  $http.get('/resources/js/cheatsheet.json').then(function(response) {
-    vm.cheatsheet = response.data;
-  });
-
   vm.showDocsNav = false;
   vm.showMainNav = false;
   vm.showMenu    = false;
@@ -72,10 +68,6 @@ angularIO.controller('AppCtrl', ['$mdDialog', '$timeout', '$http', '$sce', funct
   vm.apiType     = '';
   vm.apiFilter   = '';
 
-  vm.getSafeHtml = function(html) {
-    return $sce.trustAsHtml(html);
-  };
-
   /*
    * Prettify Code
    *

diff --git a/public/resources/js/directives/cheatsheet.js b/public/resources/js/directives/cheatsheet.js
@@ -0,0 +1,26 @@
+angularIO.directive('ngioCheatsheet', function() {
+  return {
+    controllerAs: '$ctrl',
+    controller: function($http, $attrs, $sce) {
+      var $ctrl = this;
+      $http.get($attrs.src).then(function(response) {
+        $ctrl.sections = response.data;
+      });
+      $ctrl.getSafeHtml = function(html) {
+        return $sce.trustAsHtml(html);
+      };
+    },
+    template:
+      '<div ng-if="!$ctrl.sections">Loading Cheatsheet...</div>\n' +
+      '<table ng-repeat="section in $ctrl.sections" ng-cloak>\n' +
+      '<tr>\n' +
+      '  <th>{{section.name}}</th>\n' +
+      '  <th ng-bind-html="$ctrl.getSafeHtml(section.description)"></th>\n' +
+      '</tr>\n' +
+      '<tr ng-repeat="child in section.items">\n' +
+      '  <td><code bold="child.bold" ng-compile="true">{{child.syntax}}</code></td>\n' +
+      '  <td ng-bind-html="$ctrl.getSafeHtml(child.description)"></td>\n' +
+      '</tr>\n' +
+      '</table>'
+  };
+});
diff --git a/tools/api-builder/angular.io-package/index.js b/tools/api-builder/angular.io-package/index.js
@@ -101,6 +101,12 @@ module.exports = new Package('angular.io', [basePackage, targetPackage, cheatshe
     pathTemplate: path.resolve(PUBLIC_PATH, 'resources/js/${id}'),
     outputPathTemplate: '${path}.json'
   });
+
+  computePathsProcessor.pathTemplates.push({
+    docTypes: ['cheatsheet-data'],
+    pathTemplate: '../guide/cheatsheet.json',
+    outputPathTemplate: '${path}'
+  });
 })
 
 .config(function(getLinkInfo) {

diff --git a/tools/api-builder/cheatsheet-package/index.js b/tools/api-builder/cheatsheet-package/index.js
@@ -1,6 +1,6 @@
 var Package = require('dgeni').Package;
 
-module.exports = new Package('cheatsheet', [require('../content-package')])
+module.exports = new Package('cheatsheet', [require('../content-package'), require('../target-package')])
 
 .factory(require('./services/cheatsheetItemParser'))
 .processor(require('./processors/createCheatsheetDoc'))

diff --git a/tools/api-builder/cheatsheet-package/processors/createCheatsheetDoc.js b/tools/api-builder/cheatsheet-package/processors/createCheatsheetDoc.js
@@ -9,7 +9,7 @@ module.exports = function createCheatsheetDoc(createDocMessage, renderMarkdown)
       var cheatsheetDoc = {
         id: 'cheatsheet',
         aliases: ['cheatsheet'],
-        docType: 'json-data',
+        docType: 'cheatsheet-data',
         sections: []
       };
 

diff --git a/tools/api-builder/cheatsheet-package/services/cheatsheetItemParser.js b/tools/api-builder/cheatsheet-package/services/cheatsheetItemParser.js
@@ -29,57 +29,92 @@
  * }
  * ```
  */
-module.exports = function cheatsheetItemParser() {
-
+module.exports = function cheatsheetItemParser(targetEnvironments) {
   return function(text) {
-    var index = 0;
+    var fields = getFields(text, ['syntax', 'description']);
+
     var item = {
       syntax: '',
       bold: [],
       description: ''
     };
 
-    var STATES = {
-      inSyntax: function() {
-        if (text.charAt(index) !== '`') throw new Error('item syntax must start with a backtick');
-        index += 1;
-        var syntaxStart = index;
-        while(index < text.length && text.charAt(index) !== '`') index++;
-        if (index === text.length) throw new Error('item syntax must end with a backtick');
-        item.syntax = text.substring(syntaxStart, index);
-        state = STATES.pipe;
-        index++;
-      },
-      pipe: function() {
-        if (text.charAt(index) === '|') {
-          index++;
-          while(index < text.length && /\s/.test(text.charAt(index))) index++;
-          state = STATES.bold;
-        } else {
-          state = STATES.description;
+    fields.forEach(function(field) {
+      if (!field.languages || targetEnvironments.someActive(field.languages)) {
+        switch(field.name) {
+          case 'syntax':
+            parseSyntax(field.value.trim());
+            break;
+          case 'description':
+            item.description = field.value.trim();
+            break;
         }
-      },
-      bold: function() {
-        if (text.charAt(index) !== '`') throw new Error('bold matcher must start with a backtick');
-        index += 1;
-        var boldStart = index;
-        while(index < text.length && text.charAt(index) !== '`') index++;
-        if (index === text.length) throw new Error('bold matcher must end with a backtick');
-        item.bold.push(text.substring(boldStart, index));
-        state = STATES.pipe;
-        index++;
-      },
-      description: function() {
-        item.description = text.substring(index);
-        state = null;
       }
-    };
-
-    var state = STATES.inSyntax;
-    while(state) {
-      state();
-    }
+    });
 
     return item;
+
+    function parseSyntax(text) {
+      var index = 0;
+
+      if (text.charAt(index) !== '`') throw new Error('item syntax must start with a backtick');
+
+      var start = index + 1;
+      index = text.indexOf('`', start);
+      if (index === -1) throw new Error('item syntax must end with a backtick');
+      item.syntax = text.substring(start, index);
+      start = index + 1;
+
+      // skip to next pipe
+      while(index < text.length && text.charAt(index) !== '|') index += 1;
+
+      while(text.charAt(start) === '|') {
+
+        start += 1;
+
+        // skip whitespace
+        while(start < text.length && /\s/.test(text.charAt(start))) start++;
+
+        if (text.charAt(start) !== '`') throw new Error('bold matcher must start with a backtick');
+
+        start += 1;
+        index = text.indexOf('`', start);
+        if (index === -1) throw new Error('bold matcher must end with a backtick');
+        item.bold.push(text.substring(start, index));
+        start = index + 1;
+
+      }
+
+      if (start !== text.length) {
+        throw new Error('syntax field must only contain a syntax code block and zero or more bold ' +
+                        'matcher code blocks, delimited by pipes.\n' +
+                        'Instead it was "' + text + '"');
+      }
+    }
   };
+}
+
+
+function getFields(text, fieldNames) {
+  var FIELD_START = /^([^:(]+)\(?([^)]+)?\)?:$/;
+  var lines = text.split('\n');
+  var fields = [];
+  var field, line;
+  while(lines.length) {
+    line = lines.shift();
+    var match = FIELD_START.exec(line);
+    if (match && fieldNames.indexOf(match[1]) !== -1) {
+      // start new field
+      if (field) {fields.push(field);}
+      field = { name: match[1], languages: (match[2] && match[2].split(' ')), value: ''};
+    } else {
+      if (!field) throw new Error('item must start with one of the following field specifiers:\n' +
+                            fieldNames.map(function(field) { return field + ':'; }).join('\n') + '\n' +
+                            'but instead it contained: "' + text + '"');
+      field.value += line + '\n';
+    }
+  }
+  if (field) {fields.push(field);}
+
+  return fields;
 }