docs(cheatsheet/dart): generate from dart sources (#1912)

* docs(cheatsheet/dart): generate from dart sources

Fixes #1906.

gulpfile.js

@@ -577,7 +577,6 @@ gulp.task('build-js-api-docs', ['_shred-api-examples'], function() {
 });
 
 gulp.task('build-dart-api-docs', ['_shred-api-examples', 'dartdoc'], function() {
-  // TODO(chalin): also build build-dart-cheatsheet
   return buildApiDocsForDart();
 });
 
@@ -585,11 +584,8 @@ gulp.task('build-plunkers', ['_copy-example-boilerplate'], function() {
   return plunkerBuilder.buildPlunkers(EXAMPLES_PATH, LIVE_EXAMPLES_PATH, { errFn: gutil.log });
 });
 
-gulp.task('build-dart-cheatsheet', ['build-ts-api-docs'], function() {
-  gutil.log('build-dart-cheatsheet - NOT IMPLEMENTED YET - copying TS cheatsheet data');
-  const src = './public/docs/ts/latest/guide/cheatsheet.json';
-  fs.copy(src, './public/docs/dart/latest/guide/cheatsheet.json', {clobber: true},
-    (err) => { if(err) throw err });
+gulp.task('build-dart-cheatsheet', [], function() {
+  return buildDartCheatsheet();
 });
 
 gulp.task('dartdoc', ['pub upgrade'], function() {
@@ -1190,6 +1186,32 @@ function buildApiDocs(targetLanguage) {
 }
 
 
+function buildDartCheatsheet() {
+  'use strict';
+  const ALLOWED_LANGUAGES = ['ts', 'js', 'dart'];
+  const lang = 'dart';
+  const vers = 'latest';
+  checkAngularProjectPath(ngPathFor(lang));
+  try {
+    const pkg = new Package('dartApiDocs', [require(path.resolve(TOOLS_PATH, 'dart-api-builder'))]);
+    pkg.config(function(log, targetEnvironments, writeFilesProcessor) {
+      log.level = _dgeniLogLevel;
+      ALLOWED_LANGUAGES.forEach(function(target) { targetEnvironments.addAllowed(target); });
+      targetEnvironments.activate(lang);
+      const outputPath = path.join(lang, vers, 'can-be-any-name-read-comment-below');
+      // Note: cheatsheet data gets written to: outputPath + '/../guide';
+      writeFilesProcessor.outputFolder  = outputPath;
+    });
+    var dgeni = new Dgeni([pkg]);
+    return dgeni.generate();
+  } catch(err) {
+    console.error(err);
+    console.error(err.stack);
+    throw err;
+  }
+}
+
+
 function buildApiDocsForDart() {
   const apiDir = 'api';
   const vers = 'latest';

public/docs/dart/latest/cheatsheet.jade

@@ -2,7 +2,7 @@
 .banner.grid-fluid
   .alert.is-important
     :marked
-      **Known issue:** Some cheat sheet entries are currently inaccurate, reflecting TypeScript instead of Dart.
+      This cheat sheet is provisional and subject to change.
 
 article(class="l-content-small grid-fluid docs-content")
   .cheatsheet

tools/dart-api-builder/index.js

@@ -0,0 +1,92 @@
+var fs = require('fs');
+var path = require('canonical-path');
+var Package = require('dgeni').Package;
+var basePackage = require('../api-builder/docs-package');
+var targetPackage = require('../api-builder/target-package');
+var cheatsheetPackage = require('../api-builder/cheatsheet-package');
+
+var PROJECT_PATH = path.resolve(__dirname, "../..");
+var PUBLIC_PATH = path.resolve(PROJECT_PATH, 'public');
+var DOCS_PATH = path.resolve(PUBLIC_PATH, 'docs');
+var ANGULAR_REPO_PATH = path.resolve(__dirname, '../../../angular-dart');
+var ANGULAR2_DOCS_PATH = path.resolve(ANGULAR_REPO_PATH, 'docs');
+var NG_IO_PKG_PATH = path.resolve(__dirname, "../api-builder/angular.io-package");
+
+function requireNgIoPkg(_path) { return require(path.resolve(NG_IO_PKG_PATH, _path)); }
+
+module.exports = new Package('dart-api-and-cheatsheet-builder', [basePackage, targetPackage, cheatsheetPackage])
+
+  // overrides base packageInfo and returns the one for the Angular repo.
+  .factory(require('./services/packageInfo'))
+
+  // Configure rendering
+  .config(function (templateFinder, renderDocsProcessor) {
+
+    templateFinder.templateFolders
+      .unshift(path.resolve(NG_IO_PKG_PATH, 'templates'));
+
+    // helpers are made available to the nunjucks templates
+    renderDocsProcessor.helpers.relativePath = function (from, to) {
+      return path.relative(from, to);
+    };
+  })
+
+  .config(function (parseTagsProcessor, getInjectables) {
+    const tagDefs = requireNgIoPkg('./tag-defs');
+    parseTagsProcessor.tagDefinitions =
+      parseTagsProcessor.tagDefinitions.concat(getInjectables(tagDefs));
+  })
+
+  .config(function (readFilesProcessor) {
+    // confirm that the angular repo is actually there.
+    if (!fs.existsSync(ANGULAR_REPO_PATH)) {
+      throw new Error('dart-api-and-cheatsheet-builder task requires the angular2 repo to be at ' + ANGULAR_REPO_PATH);
+    }
+    readFilesProcessor.basePath = DOCS_PATH;
+    readFilesProcessor.sourceFiles = [{
+      basePath: ANGULAR2_DOCS_PATH,
+      include: path.resolve(ANGULAR2_DOCS_PATH, 'cheatsheet/*.md')
+    }];
+  })
+
+  .config(function (convertPrivateClassesToInterfacesProcessor,
+    createOverviewDump,
+    extractDirectiveClassesProcessor,
+    extractJSDocCommentsProcessor,
+    extractTitleFromGuides,
+    generateNavigationDoc,
+    mergeDecoratorDocs,
+    readTypeScriptModules
+  ) {
+    // Clear out unwanted processors
+    createOverviewDump.$enabled = false;
+    convertPrivateClassesToInterfacesProcessor.$enabled = false;
+    extractDirectiveClassesProcessor.$enabled = false;
+    extractJSDocCommentsProcessor.$enabled = false;
+    extractTitleFromGuides.$enabled = false;
+    generateNavigationDoc.$enabled = false;
+    mergeDecoratorDocs.$enabled = false;
+    readTypeScriptModules.$enabled = false;
+  })
+
+  .config(function (computePathsProcessor) {
+    computePathsProcessor.pathTemplates.push({
+      docTypes: ['cheatsheet-data'],
+      pathTemplate: '../guide/cheatsheet.json',
+      outputPathTemplate: '${path}'
+    });
+  })
+
+  .config(function (getLinkInfo) {
+    getLinkInfo.relativeLinks = true;
+  })
+
+  .config(function (templateEngine, getInjectables) {
+    templateEngine.filters = templateEngine.filters.concat(getInjectables([
+      requireNgIoPkg('./rendering/trimBlankLines'),
+      requireNgIoPkg('./rendering/toId'),
+      requireNgIoPkg('./rendering/indentForMarkdown')
+    ]));
+  })
+
+  ;

tools/dart-api-builder/services/packageInfo.js

@@ -0,0 +1,38 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('canonical-path');
+
+/**
+ * Load information about this project from the pubspec.yaml
+ * @return {Object} The package information
+ */
+module.exports = function packageInfo() {
+  const ngPath = '../angular-dart';
+  const angularPubspec = path.join(ngPath, 'pubspec.yaml');
+  const pubspec = fs.readFileSync(angularPubspec, 'UTF-8').split('\n');
+
+  const info = {
+    version: _get(pubspec, 'version'),
+    repository: {
+      type: 'git', //? 'pub' @ 'https://pub.dartlang.org/packages/angular2'
+      // Not sure `url has a user visible impact on the generated cheatsheet. 
+      url: 'https://github.com/angular/angular.git', 
+    }
+  };
+  return info;
+}
+
+// Array.prototype.find doesn't seem to be working.
+// console.error([1, 'a', 2].find((x) => x === 'a')); // --> -1
+function _find(arr, test) {
+  for (let x of arr) {
+    // console.error(`Looking at: ${x}`);
+    if (test(x)) return x;
+  }
+}
+
+function _get(lines, tag) {
+  const line = _find(lines, (line) => line.startsWith(tag));
+  return line.match(/^\w+: (.*)/)[1] || 'unknown';
+}