chore(doc-gen): put typescript stuff into its own package

This means that we can now run just the d.ts file generation by running:

```bash
gulp docs/typings
```

In addition the type definition generation was messing with the other docs tasks
so separating it also fixes problems there.

docs/angular.io-package/index.js

@@ -21,12 +21,11 @@ module.exports = new Package('angular.io', [basePackage])
   writeFilesProcessor.outputFolder  = 'dist/angular.io';
 })
 
-.config(function(readFilesProcessor, generateNavigationDoc, createOverviewDump, createTypeDefinitionFile) {
+.config(function(readFilesProcessor, generateNavigationDoc, createOverviewDump) {
   // Clear out unwanted processors
   readFilesProcessor.$enabled = false;
   generateNavigationDoc.$enabled = false;
   createOverviewDump.$enabled = false;
-  createTypeDefinitionFile.$enabled = false;
 })
 
 

docs/docs-package/index.js

@@ -3,45 +3,21 @@ require('../../tools/transpiler/index.js').init();
 var Package = require('dgeni').Package;
 var jsdocPackage = require('dgeni-packages/jsdoc');
 var nunjucksPackage = require('dgeni-packages/nunjucks');
+var typescriptPackage = require('../typescript-package');
 var linksPackage = require('../links-package');
 var gitPackage = require('dgeni-packages/git');
 var path = require('canonical-path');
 
-var PARTIAL_PATH = 'partials';
-var MODULES_DOCS_PATH = PARTIAL_PATH + '/modules';
-var GUIDES_PATH = PARTIAL_PATH + '/guides';
-
 // Define the dgeni package for generating the docs
-module.exports = new Package('angular', [jsdocPackage, nunjucksPackage, linksPackage, gitPackage])
+module.exports = new Package('angular-v2-docs', [jsdocPackage, nunjucksPackage, typescriptPackage, linksPackage, gitPackage])
 
 // Register the services and file readers
-.factory(require('./services/modules'))
-.factory(require('./services/tsParser'))
-.factory(require('./services/tsParser/createCompilerHost'))
-.factory(require('./services/tsParser/getFileInfo'))
-.factory(require('./services/tsParser/getExportDocType'))
-.factory(require('./services/tsParser/getContent'))
 .factory(require('./readers/ngdoc'))
 
-.factory('EXPORT_DOC_TYPES', function() {
-  return [
-    'class',
-    'interface',
-    'function',
-    'var',
-    'const',
-    'enum',
-    'type-alias'
-  ];
-})
-
-
 // Register the processors
-.processor(require('./processors/readTypeScriptModules'))
 .processor(require('./processors/generateNavigationDoc'))
 .processor(require('./processors/extractTitleFromGuides'))
 .processor(require('./processors/createOverviewDump'))
-.processor(require('./processors/createTypeDefinitionFile'))
 
 
 // Configure the log service
@@ -67,7 +43,7 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage, linksPac
     '*/*.@(js|es6|ts)',
     '*/src/**/*.@(js|es6|ts)'
   ];
-  readTypeScriptModules.basePath = 'modules';
+  readTypeScriptModules.basePath = path.resolve(readFilesProcessor.basePath, 'modules');
 })
 
 
@@ -122,13 +98,7 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage, linksPac
 
 
 // Configure ids and paths
-.config(function(computeIdsProcessor, computePathsProcessor, EXPORT_DOC_TYPES) {
-
-  computeIdsProcessor.idTemplates.push({
-    docTypes: ['member'],
-    idTemplate: '${classDoc.id}.${name}',
-    getAliases: function(doc) { return [doc.id]; }
-  });
+.config(function(computeIdsProcessor, computePathsProcessor) {
 
   computeIdsProcessor.idTemplates.push({
     docTypes: ['guide'],
@@ -144,29 +114,9 @@ module.exports = new Package('angular', [jsdocPackage, nunjucksPackage, linksPac
     getAliases: function(doc) { return [doc.id]; }
   });
 
-
-  computePathsProcessor.pathTemplates.push({
-    docTypes: ['module'],
-    pathTemplate: '/${id}',
-    outputPathTemplate: MODULES_DOCS_PATH + '/${id}/index.html'
-  });
-
-  computePathsProcessor.pathTemplates.push({
-    docTypes: EXPORT_DOC_TYPES,
-    pathTemplate: '${moduleDoc.path}/${name}',
-    outputPathTemplate: MODULES_DOCS_PATH + '/${path}/index.html'
-  });
-
-  computePathsProcessor.pathTemplates.push({
-    docTypes: ['member'],
-    pathTemplate: '${classDoc.path}/${name}',
-    getOutputPath: function() {} // These docs are not written to their own file, instead they are part of their class doc
-  });
-
-
   computePathsProcessor.pathTemplates.push({
     docTypes: ['guide'],
     pathTemplate: '/${id}',
-    outputPathTemplate: GUIDES_PATH + '/${id}.html'
+    outputPathTemplate: 'partials/guides/${id}.html'
   });
 });

docs/public-docs-package/index.js

@@ -1,7 +1,7 @@
 var Package = require('dgeni').Package;
-var basePackage = require('../dgeni-package');
+var basePackage = require('../docs-package');
 
-module.exports = new Package('angular-public', [basePackage])
+module.exports = new Package('angular-v2-public-docs', [basePackage])
 
 .config(function(readTypeScriptModules) {
   readTypeScriptModules.sourceFiles = [

docs/typescript-definition-package/index.js

@@ -0,0 +1,89 @@
+var Package = require('dgeni').Package;
+var jsdocPackage = require('dgeni-packages/jsdoc');
+var nunjucksPackage = require('dgeni-packages/nunjucks');
+var typescriptPackage = require('../typescript-package');
+var gitPackage = require('dgeni-packages/git');
+var path = require('canonical-path');
+
+// Define the dgeni package for generating the docs
+module.exports = new Package('angular-v2-docs', [jsdocPackage, nunjucksPackage, typescriptPackage, gitPackage])
+
+// Register the processors
+.processor(require('./processors/createTypeDefinitionFile'))
+
+.config(function(readFilesProcessor, inlineTagProcessor) {
+  readFilesProcessor.basePath = path.resolve(__dirname, '../..');
+  // Don't run unwanted processors
+  readFilesProcessor.$enabled = false;
+  inlineTagProcessor.$enabled = false;
+})
+
+
+// Configure the log service
+.config(function(log) {
+  log.level = 'info';
+})
+
+
+.config(function(renderDocsProcessor, versionInfo) {
+  renderDocsProcessor.extraData.versionInfo = versionInfo;
+})
+
+.config(function(readFilesProcessor, inlineTagProcessor, readTypeScriptModules) {
+
+  // Don't run unwanted processors
+  readFilesProcessor.$enabled = false; // We are not using the normal file reading processor
+  inlineTagProcessor.$enabled = false; // We are not actually processing the inline link tags
+
+  // Configure file reading
+  readFilesProcessor.basePath = path.resolve(__dirname, '../..');
+  readTypeScriptModules.sourceFiles = [
+    'angular2/angular2.ts',
+    'angular2/router.ts'
+  ];
+  readTypeScriptModules.basePath = path.resolve(path.resolve(__dirname, '../../modules'));
+})
+
+
+.config(function(parseTagsProcessor, getInjectables) {
+  parseTagsProcessor.tagDefinitions.push(require('./tag-defs/public'));
+  parseTagsProcessor.tagDefinitions.push(require('./tag-defs/private'));
+  parseTagsProcessor.tagDefinitions.push(require('./tag-defs/exportedAs'));
+
+  // We actually don't want to parse param docs in this package as we are getting the data out using TS
+  parseTagsProcessor.tagDefinitions.forEach(function(tagDef) {
+    if (tagDef.name === 'param') {
+      tagDef.docProperty = 'paramData';
+      tagDef.transforms = [];
+    }
+  });
+
+})
+
+
+// Configure file writing
+.config(function(writeFilesProcessor) {
+  writeFilesProcessor.outputFolder  = 'dist/docs';
+})
+
+
+// Configure rendering
+.config(function(templateFinder, templateEngine) {
+
+  // Nunjucks and Angular conflict in their template bindings so change Nunjucks
+  templateEngine.config.tags = {
+    variableStart: '{$',
+    variableEnd: '$}'
+  };
+
+  templateFinder.templateFolders
+      .unshift(path.resolve(__dirname, 'templates'));
+
+  templateFinder.templatePatterns = [
+    '${ doc.template }',
+    '${ doc.id }.${ doc.docType }.template.html',
+    '${ doc.id }.template.html',
+    '${ doc.docType }.template.html',
+    'common.template.html'
+  ];
+});

docs/typescript-definition-package/processors/createTypeDefinitionFile.js

@@ -61,11 +61,12 @@ module.exports = function createTypeDefinitionFile(log) {
         });
       });
 
-      _.forEach(typeDefDocs, function(doc) {
+      return _.filter(typeDefDocs, function(doc) {
         _.forEach(doc.moduleDocs, function(modDoc, alias) {
-          if (!modDoc.doc) {
+          if (!doc || !modDoc.doc) {
             log.error('createTypeDefinitionFile processor: no such module "' + alias + '" (Did you forget to add it to the modules to load?)');
             doc = null;
+            return;
           }
           _.forEach(modDoc.doc.exports, function(exportDoc) {
 
@@ -86,9 +87,7 @@ module.exports = function createTypeDefinitionFile(log) {
             }
           });
         });
-        if (doc) {
-          docs.push(doc);
-        }
+        return !!doc;
       });
     }
   };

docs/typescript-definition-package/tag-defs/exportedAs.js

@@ -0,0 +1,4 @@
+module.exports = {
+  name: 'exportedAs',
+  multi: true
+};

docs/typescript-definition-package/tag-defs/private.js

@@ -0,0 +1,4 @@
+module.exports = {
+  name: 'private',
+  transforms: function(doc, tag) { return true; }
+};

docs/typescript-definition-package/tag-defs/public.js

@@ -0,0 +1,4 @@
+module.exports = {
+  name: 'public',
+  transforms: function(doc, tag) { return true; }
+};

docs/typescript-definition-package/templates/angular2/angular2.d.ts.template.html

@@ -0,0 +1,32 @@
+{% extends '../type-definition.template.html' %}
+{% block staticDeclarations %}
+// Angular depends transitively on these libraries.
+// If you don't have them installed you can run
+// $ tsd query es6-promise rx rx-lite --action install --save
+///<reference path="../es6-promise/es6-promise.d.ts"/>
+///<reference path="../rx/rx.d.ts"/>
+
+interface List<T> extends Array<T> {}
+interface Map<K,V> {}
+interface StringMap<K,V> extends Map<K,V> {}
+
+declare module ng {
+  type SetterFn = typeof Function;
+  type int = number;
+  interface Type extends Function {
+    new (...args);
+  }
+
+  // See https://github.com/Microsoft/TypeScript/issues/1168
+  class BaseException /* extends Error */ {
+    message: string;
+    stack: string;
+    toString(): string;
+  }
+  interface InjectableReference {}
+}
+{% endblock %}
+
+declare module "angular2/angular2" {
+  export = ng;
+}

docs/typescript-definition-package/templates/type-definition.template.html

@@ -0,0 +1,72 @@
+
+{%- macro commentBlock(doc, level) -%}
+{%- if doc.content | trim %}
+
+{% if level > 1 %}{$ '/**' | indent(level-1, true) | replace(r/\n$/, "") $}{% else %}/**{% endif %}
+{$ doc.content | trim | replace(r/^/gm, "* ") | indent(level, true) | replace(r/\n$/, "") $}
+{$ '*/' | indent(level, true) | replace(r/\n$/, "") $}{% endif -%}
+{%- endmacro -%}
+
+
+{%- macro memberInfo(member) -%}
+{$ commentBlock(member, 5) $}
+     {$ member.name $}{% if member.optional %}?{% endif -%}
+{% if member.typeParameters %}<{% for typeParam in member.typeParameters %}{$ typeParam $}{% if not loop.last %}, {% endif %}{% endfor %}>{% endif -%}
+{%- if member.parameters -%}({% for param in member.parameters %}{$ param $}{% if not loop.last %}, {% endif %}{% endfor %}){%- endif -%}
+{%- if member.returnType == 'Directive' %}: DirectiveAnnotation{%- elif member.returnType -%}: {$ member.returnType $}{%- else -%}: void
+{%- endif -%};
+{%- endmacro -%}
+
+
+// Type definitions for Angular v{$ versionInfo.currentVersion.full | replace(r/\+/, "_") $}
+// Project: http://angular.io/
+// Definitions by: angular team <https://github.com/angular/>
+// Definitions: https://github.com/borisyankov/DefinitelyTyped
+
+// ***********************************************************
+// This file is generated by the Angular build process.
+// Please do not create manual edits or send pull requests
+// modifying this file.
+// ***********************************************************
+{% block staticDeclarations %}{% endblock %}
+{% for alias, module in doc.moduleDocs %}
+{$ commentBlock(module.doc, 1) $}
+declare module ng {
+
+  {%- for export in module.doc.exports -%}
+  {%- if export.content -%}
+    {$ commentBlock(export, 3) $}
+  {%- endif %}
+  {$ export.docType $} {$ export.name $}{$ export.typeParams $}{%- if export.heritage == ' extends Directive' %} extends DirectiveAnnotation{% else %}{$ export.heritage $}{% endif %}
+  {%- if export.docType == 'class' or export.docType == 'interface' %} {
+  {%- if export.newMember %}
+    {$ memberInfo(export.newMember) $}
+  {% endif %}
+  {%- if export.callMember %}
+    {$ memberInfo(export.callMember) $}
+  {% endif -%}
+  {%- for member in export.members %}
+    {$ memberInfo(member) $}
+  {%- endfor %}
+  }
+
+  {%- elif export.docType == 'enum' %} {
+    {%- for member in export.members %}
+    {$ member $}{% if not loop.last %},
+    {%- endif -%}
+    {%- endfor %}
+  }
+
+  {%- else -%}
+    {% if export.parameters %}({% for param in export.parameters %}{$ param $}{% if not loop.last %}, {% endif %}{% endfor %}){%- endif %}
+    {%- if export.returnType %} : {$ export.returnType $} {% endif -%}
+    ;
+  {%- endif %}
+  {% endfor %}
+}
+
+{% endfor %}
+
+declare module "angular2/angular2" {
+  export = ng;
+}

docs/typescript-package/index.js

@@ -0,0 +1,70 @@
+require('../../tools/transpiler/index.js').init();
+
+var basePackage = require('dgeni-packages/base');
+var Package = require('dgeni').Package;
+var path = require('canonical-path');
+
+// Define the dgeni package for generating the docs
+module.exports = new Package('typescript-parsing', [basePackage])
+
+// Register the services and file readers
+.factory(require('./services/modules'))
+.factory(require('./services/tsParser'))
+.factory(require('./services/tsParser/createCompilerHost'))
+.factory(require('./services/tsParser/getFileInfo'))
+.factory(require('./services/tsParser/getExportDocType'))
+.factory(require('./services/tsParser/getContent'))
+
+.factory('EXPORT_DOC_TYPES', function() {
+  return [
+    'class',
+    'interface',
+    'function',
+    'var',
+    'const',
+    'enum',
+    'type-alias'
+  ];
+})
+
+
+// Register the processors
+.processor(require('./processors/readTypeScriptModules'))
+
+
+// Configure the log service
+.config(function(log) {
+  log.level = 'warn';
+})
+
+
+// Configure ids and paths
+.config(function(computeIdsProcessor, computePathsProcessor, EXPORT_DOC_TYPES) {
+
+  computeIdsProcessor.idTemplates.push({
+    docTypes: ['member'],
+    idTemplate: '${classDoc.id}.${name}',
+    getAliases: function(doc) { return [doc.id]; }
+  });
+
+  computePathsProcessor.pathTemplates.push({
+    docTypes: ['member'],
+    pathTemplate: '${classDoc.path}/${name}',
+    getOutputPath: function() {} // These docs are not written to their own file, instead they are part of their class doc
+  });
+
+  var MODULES_DOCS_PATH = 'partials/modules';
+
+  computePathsProcessor.pathTemplates.push({
+    docTypes: ['module'],
+    pathTemplate: '/${id}',
+    outputPathTemplate: MODULES_DOCS_PATH + '/${id}/index.html'
+  });
+
+  computePathsProcessor.pathTemplates.push({
+    docTypes: EXPORT_DOC_TYPES,
+    pathTemplate: '${moduleDoc.path}/${name}',
+    outputPathTemplate: MODULES_DOCS_PATH + '/${path}/index.html'
+  });
+
+});

docs/typescript-package/mocks/mockPackage.js

@@ -0,0 +1,11 @@
+var Package = require('dgeni').Package;
+
+module.exports = function mockPackage() {
+
+  return new Package('mockPackage', [require('../')])
+
+  // provide a mock log service
+  .factory('log', function() { return require('dgeni/lib/mocks/log')(false); })
+  .factory('templateEngine', function() { return {}; });
+
+};

docs/typescript-package/mocks/tsParser/importedSrc.ts

@@ -0,0 +1 @@
+export var x = 100;

docs/typescript-package/mocks/tsParser/testSrc.ts

@@ -0,0 +1,34 @@
+/**
+ * @module
+ * @description
+ * This is the module description
+ */
+
+export * from 'importedSrc';
+
+/**
+ * This is some random other comment
+ */
+
+/**
+ * This is MyClass
+ */
+export class MyClass {
+  message: String;
+
+  /**
+   * Create a new MyClass
+   * @param {String} name The name to say hello to
+   */
+  constructor(name) { this.message = 'hello ' + name; }
+
+  /**
+   * Return a greeting message
+   */
+  greet() { return this.message; }
+}
+
+/**
+ * An exported function
+ */
+export var myFn = (val: number) => return val * 2;

docs/typescript-package/processors/readTypeScriptModules.js

@@ -3,7 +3,7 @@ var path = require('canonical-path');
 var _ = require('lodash');
 var ts = require('typescript');
 
-module.exports = function readTypeScriptModules(tsParser, readFilesProcessor, modules, getFileInfo,
+module.exports = function readTypeScriptModules(tsParser, modules, getFileInfo,
                                                 getExportDocType, getContent, log) {
 
   return {
@@ -37,7 +37,7 @@ module.exports = function readTypeScriptModules(tsParser, readFilesProcessor, mo
       var hidePrivateMembers = this.hidePrivateMembers;
       var sortClassMembers = this.sortClassMembers;
 
-      var basePath = path.resolve(readFilesProcessor.basePath, this.basePath);
+      var basePath = path.resolve(this.basePath);
       var filesPaths = expandSourceFiles(this.sourceFiles, basePath);
       var parseInfo = tsParser.parse(filesPaths, this.basePath);
       var moduleSymbols = parseInfo.moduleSymbols;

docs/typescript-package/services/tsParser/createCompilerHost.spec.js

@@ -12,7 +12,7 @@ describe('createCompilerHost', function() {
     var createCompilerHost = injector.get('createCompilerHost');
 
     options = { charset: 'utf8' };
-    baseDir = path.resolve(__dirname, '../../mocks/');
+    baseDir = path.resolve(__dirname, '../../mocks/tsParser');
     extensions = ['.ts', '.js'];
 
     host = createCompilerHost(options, baseDir, extensions);
@@ -30,8 +30,8 @@ describe('createCompilerHost', function() {
       var sourceFile = host.getSourceFile('testSrc.js');
       expect(sourceFile.fileName).toEqual('testSrc.ts');
 
-      sourceFile = host.getSourceFile('mockPackage.ts');
-      expect(sourceFile.fileName).toEqual('mockPackage.js');
+      sourceFile = host.getSourceFile('../mockPackage.ts');
+      expect(sourceFile.fileName).toEqual('../mockPackage.js');
     });
   });
 

docs/typescript-package/services/tsParser/index.spec.js

@@ -1,4 +1,4 @@
-var mockPackage = require('../mocks/mockPackage');
+var mockPackage = require('../../mocks/mockPackage');
 var Dgeni = require('dgeni');
 var path = require('canonical-path');
 
@@ -12,7 +12,7 @@ describe('tsParser', function() {
   });
 
   it("should parse a TS file", function() {
-    var parseInfo = parser.parse(['testSrc.ts'], path.resolve(__dirname, '../mocks/'));
+    var parseInfo = parser.parse(['testSrc.ts'], path.resolve(__dirname, '../../mocks/tsParser'));
     var tsModules = parseInfo.moduleSymbols;
     expect(tsModules.length).toEqual(1);
     expect(tsModules[0].exportArray.length).toEqual(3);

gulpfile.js

@@ -380,10 +380,10 @@ gulp.task('docs/bower', function() {
 });
 
 
-function createDocsTasks(publicBuild) {
-  var dgeniPackage = publicBuild ? './docs/public-docs-package' : './docs/dgeni-package';
-  var distDocsPath = publicBuild ? 'dist/public_docs' : 'dist/docs';
-  var taskPrefix = publicBuild ? 'public_docs' : 'docs';
+function createDocsTasks(options) {
+  var dgeniPackage = options.package;
+  var distDocsPath = options.path;
+  var taskPrefix = options.prefix;
 
   gulp.task(taskPrefix + '/dgeni', function() {
     try {
@@ -423,8 +423,9 @@ function createDocsTasks(publicBuild) {
   });
 }
 
-createDocsTasks(true);
-createDocsTasks(false);
+
+createDocsTasks({ package: './docs/docs-package', path: 'dist/docs', prefix: 'docs'});
+createDocsTasks({ package: './docs/public-docs-package', path: 'dist/public_docs', prefix: 'public_docs'});
 
 gulp.task('docs/angular.io', ['build/clean.docs_angular_io'], function() {
   try {
@@ -437,6 +438,17 @@ gulp.task('docs/angular.io', ['build/clean.docs_angular_io'], function() {
   }
 });
 
+gulp.task('docs/typings', [], function() {
+  try {
+    var dgeni = new Dgeni([require('./docs/typescript-definition-package')]);
+    return dgeni.generate();
+  } catch(x) {
+    console.log(x);
+    console.log(x.stack);
+    throw x;
+  }
+});
+
 
 // ------------------
 // CI tests suites
@@ -642,7 +654,7 @@ gulp.task('post-test-checks', function(done) {
 });
 
 
-gulp.task('!pre.test.typings', [], function() {
+gulp.task('!pre.test.typings', ['docs/typings'], function() {
   return gulp
     .src([
       'modules/angular2/typings/**/*'], {