diff --git a/gulpfile.js b/gulpfile.js index ab6df29ec5..3b0743ac34 100644 --- a/gulpfile.js +++ b/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'; diff --git a/public/docs/dart/latest/cheatsheet.jade b/public/docs/dart/latest/cheatsheet.jade index 739ad031ab..77c0f11d36 100644 --- a/public/docs/dart/latest/cheatsheet.jade +++ b/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 diff --git a/tools/dart-api-builder/index.js b/tools/dart-api-builder/index.js new file mode 100644 index 0000000000..4d2a0618ef --- /dev/null +++ b/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') + ])); + }) + + ; diff --git a/tools/dart-api-builder/services/packageInfo.js b/tools/dart-api-builder/services/packageInfo.js new file mode 100644 index 0000000000..53db824168 --- /dev/null +++ b/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'; +}