docs in socks

scripts/docs/dgeni-config.js

@@ -2,20 +2,27 @@ 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('path');
 
 // Define the dgeni package for generating the docs
-module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, typescriptPackage/*, linksPackage, gitPackage*/])
+module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, typescriptPackage, linksPackage, gitPackage])
 
 .config(function(log) {
-  log.level = 'debug' //'warn';
+  log.level = 'silly' //'warn';
 })
 
-.config(function(readFilesProcessor, inlineTagProcessor, readTypeScriptModules, createTypeDefinitionFile) {
+.config(function(renderDocsProcessor, versionInfo) {
+  renderDocsProcessor.extraData.versionInfo = versionInfo;
+})
+
+//configure file reading
+.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
+  // inlineTagProcessor.$enabled = false; // We are not actually processing the inline link tags
 
   // jsdocFileReader.defaultPattern = /\.(j|t)s$/;
   // readFilesProcessor.fileReaders = [jsdocFileReader];
@@ -27,6 +34,72 @@ module.exports = new Package('ionic-v2-docs', [jsdocPackage, nunjucksPackage, ty
   readTypeScriptModules.sourceFiles = [
     'ionic/ionic.ts'
   ];
+  readTypeScriptModules.hidePrivateMembers = true;
+})
 
-  writeFilesProcessor.outputFolder = 'dist/docs'
-});
+.config(function(parseTagsProcessor) {
+  // 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 links
+.config(function(getLinkInfo) {
+  getLinkInfo.useFirstAmbiguousLink = false;
+})
+
+// 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 the Nunjucks
+  templateEngine.config.tags = {
+    variableStart: '{$',
+    variableEnd: '$}'
+  };
+
+  templateFinder.templateFolders.unshift(path.resolve(__dirname, 'templates'));
+
+  // Specify how to match docs to templates.
+  // In this case we just use the same static template for all docs
+  templateFinder.templatePatterns.unshift('common.template.html');
+
+  // templateFinder.templatePatterns = [
+  //   '${ doc.template }',
+  //   '${ doc.id }.${ doc.docType }.template.html',
+  //   '${ doc.id }.template.html',
+  //   '${ doc.docType }.template.html',
+  //   'common.template.html'
+  // ];
+})
+
+// Configure ids and paths
+// .config(function(computeIdsProcessor, computePathsProcessor) {
+//   computeIdsProcessor.idTemplates.push({
+//     docTypes: ['guide'],
+//     getId: function(doc) {
+//       return doc.fileInfo.relativePath
+//                     // path should be relative to `modules` folder
+//                     .replace(/.*\/?modules\//, '')
+//                     // path should not include `/docs/`
+//                     .replace(/\/docs\//, '/')
+//                     // path should not have a suffix
+//                     .replace(/\.\w*$/, '');
+//     },
+//     getAliases: function(doc) { return [doc.id]; }
+//   });
+//
+//   computePathsProcessor.pathTemplates.push({
+//     docTypes: ['guide'],
+//     pathTemplate: '/${id}',
+//     outputPathTemplate: 'partials/guides/${id}.html'
+//   });
+// });

scripts/docs/links-package/index.js

@@ -0,0 +1,13 @@
+var Package = require('dgeni').Package;
+
+module.exports = new Package('links', [])
+
+.factory(require('./inline-tag-defs/link'))
+.factory(require('dgeni-packages/ngdoc/services/getAliases'))
+.factory(require('dgeni-packages/ngdoc/services/getDocFromAlias'))
+.factory(require('./services/getLinkInfo'))
+
+.config(function(inlineTagProcessor, linkInlineTagDef) {
+  debugger;
+  inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef);
+});

scripts/docs/links-package/inline-tag-defs/link.js

@@ -0,0 +1,33 @@
+var INLINE_LINK = /(\S+)(?:\s+([\s\S]+))?/;
+
+/**
+ * @dgService linkInlineTagDef
+ * @description
+ * Process inline link tags (of the form {@link some/uri Some Title}), replacing them with HTML anchors
+ * @kind function
+ * @param  {Object} url   The url to match
+ * @param  {Function} docs error message
+ * @return {String}  The html link information
+ *
+ * @property {boolean} relativeLinks Whether we expect the links to be relative to the originating doc
+ */
+module.exports = function linkInlineTagDef(getLinkInfo, createDocMessage, log) {
+  return {
+    name: 'link',
+    description: 'Process inline link tags (of the form {@link some/uri Some Title}), replacing them with HTML anchors',
+    handler: function(doc, tagName, tagDescription) {
+
+      // Parse out the uri and title
+      return tagDescription.replace(INLINE_LINK, function(match, uri, title) {
+
+        var linkInfo = getLinkInfo(uri, title, doc);
+
+        if ( !linkInfo.valid ) {
+          log.warn(createDocMessage(linkInfo.error, doc));
+        }
+
+        return "<a href='" + linkInfo.url + "'>" + linkInfo.title + "</a>";
+      });
+    }
+  };
+};

scripts/docs/links-package/services/getLinkInfo.js

@@ -0,0 +1,72 @@
+var _ = require('lodash');
+var path = require('canonical-path');
+
+/**
+ * @dgService getLinkInfo
+ * @description
+ * Get link information to a document that matches the given url
+ * @kind function
+ * @param  {String} url   The url to match
+ * @param  {String} title An optional title to return in the link information
+ * @return {Object}       The link information
+ *
+ * @property {boolean} relativeLinks Whether we expect the links to be relative to the originating doc
+ */
+module.exports = function getLinkInfo(getDocFromAlias, encodeCodeBlock, log) {
+
+  return function getLinkInfoImpl(url, title, currentDoc) {
+    var linkInfo = {
+      url: url,
+      type: 'url',
+      valid: true,
+      title: title || url
+    };
+
+    if ( !url ) {
+      throw new Error('Invalid url');
+    }
+
+    var docs = getDocFromAlias(url, currentDoc);
+
+    if ( !getLinkInfoImpl.useFirstAmbiguousLink && docs.length > 1 ) {
+
+      linkInfo.valid = false;
+      linkInfo.errorType = 'ambiguous';
+      linkInfo.error = 'Ambiguous link: "' + url + '".\n' +
+        docs.reduce(function(msg, doc) { return msg + '\n  "' + doc.id + '" ('+ doc.docType + ') : (' + doc.path + ' / ' + doc.fileInfo.relativePath + ')'; }, 'Matching docs: ');
+
+    } else if ( docs.length >= 1 ) {
+
+      linkInfo.url = docs[0].path;
+      linkInfo.title = title || encodeCodeBlock(docs[0].name, true);
+      linkInfo.type = 'doc';
+
+      if ( getLinkInfoImpl.relativeLinks && currentDoc && currentDoc.path ) {
+        var currentFolder = path.dirname(currentDoc.path);
+        var docFolder = path.dirname(linkInfo.url);
+        var relativeFolder = path.relative(path.join('/', currentFolder), path.join('/', docFolder));
+        linkInfo.url = path.join(relativeFolder, path.basename(linkInfo.url));
+        log.debug(currentDoc.path, docs[0].path, linkInfo.url);
+      }
+
+    } else if ( url.indexOf('#') > 0 ) {
+      var pathAndHash = url.split('#');
+      linkInfo = getLinkInfoImpl(pathAndHash[0], title, currentDoc);
+      linkInfo.url = linkInfo.url + '#' + pathAndHash[1];
+      return linkInfo;
+
+    } else if ( url.indexOf('/') === -1 && url.indexOf('#') !== 0 ) {
+
+      linkInfo.valid = false;
+      linkInfo.errorType = 'missing';
+      linkInfo.error = 'Invalid link (does not match any doc): "' + url + '"';
+
+    } else {
+
+      linkInfo.title = title || (( url.indexOf('#') === 0 ) ? url.substring(1) : path.basename(url, '.html'));
+
+    }
+
+    return linkInfo;
+  };
+};

scripts/docs/templates/common.template.html

@@ -0,0 +1,51 @@
+{% macro paramList(params) -%}
+  {%- if params -%}<span class="params">(
+    {%- for param in params -%}
+      <span class="param">{$ param | escape $}{% if not loop.last %}, {% endif %}</span>
+    {%- endfor %})</span>
+  {%- endif %}
+{%- endmacro -%}
+{% macro githubViewLink(doc) -%}
+  <a href="https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInfo.repo $}/tree/master/{$ doc.fileInfo.relativePath $}#L{$ doc.location.start.line+1 $}-L{$ doc.location.end.line+1 $}">{$ doc.fileInfo.relativePath $} (line {$ doc.location.start.line+1 $})</a>
+{%- endmacro -%}
+
+{% block body %}
+<h1 class="class export">{$ doc.name $} <span class="type">{$ doc.docType $}</span></h1>
+<p class="module">exported from {@link {$ doc.moduleDoc.id $} {$doc.moduleDoc.id $} }<br/>
+defined in {$ githubViewLink(doc) $}
+</p>
+<p>{$ doc.description | marked $}</p>
+
+{%- if doc.decorators %}
+<h2>Annotations</h2>
+{%- for decorator in doc.decorators %}
+  <h3 class="annotation">@{$ decorator.name $}{$ paramList(decorator.arguments) $}</h3>
+{% endfor %}
+{% endif -%}
+
+{%- if doc.constructorDoc or doc.members.length -%}
+<h2>Members</h2>
+
+{%- if doc.constructorDoc %}
+  <section class="member constructor">
+    <h1 id="constructor" class="name">{$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.params) $}</h1>
+    {% marked %}
+      {$ doc.constructorDoc.description $}
+    {% endmarked %}
+  </section>
+{% endif -%}
+
+{%- for member in doc.members %}{% if not member.private %}
+  <section class="member">
+    <h1 id="{$ member.name $}" class="name">
+      {$ member.name $}{% if member.optional %}?{% endif %}{$ paramList(member.params) $}
+    </h1>
+    {% marked %}
+      {$ member.description $}
+    {% endmarked %}
+  </section>
+
+{% endif %}{% endfor %}
+{%- endif -%}
+
+{% endblock %}

scripts/docs/typescript-definition-package/index.js

@@ -0,0 +1,100 @@
+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, createTypeDefinitionFile) {
+
+  // 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'));
+  
+  createTypeDefinitionFile.typeDefinitions = [
+      {
+        id: 'angular2/angular2',
+        modules: {
+          'angular2/angular2': 'angular2/angular2',
+        }
+      },
+      {
+        id: 'angular2/router',
+        modules: {
+          'angular2/router': 'angular2/router'
+        }
+      }    
+  ];
+})
+
+
+.config(function(parseTagsProcessor, getInjectables) {
+  // 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'
+  ];
+});

scripts/docs/typescript-definition-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 {}; });
+
+};

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

@@ -0,0 +1,86 @@
+var _ = require('lodash');
+var path = require('canonical-path');
+
+module.exports = function createTypeDefinitionFile(log) {
+
+  return {
+    $runAfter: ['processing-docs'],
+    $runBefore: ['docs-processed'],
+    $validate: {
+      dtsPath: { presence: true },
+      dtsExtension: { presence: true },
+      typeDefinitions: { presence: true }
+    },
+    dtsPath: 'typings',
+    dtsExtension: '.d.ts',
+    typeDefinitions: [],
+    $process: function(docs) {
+      var dtsPath = this.dtsPath;
+      var dtsExtension = this.dtsExtension;
+
+      // For each type definition that we wish to create we define a dgeni "doc" for it
+      var typeDefDocs = _.map(this.typeDefinitions, function(def) {
+
+        var id = def.id + dtsExtension;
+        var docPath = path.join(dtsPath, id);
+
+        return {
+          docType: 'type-definition',
+          id: id,
+          aliases: [id],
+          path: docPath,
+          outputPath: docPath,
+          // A type definition may include a number of top level modules
+          // And those modules could be aliased (such as 'angular2/angular2.api' -> 'angular2/angular2')
+          moduleDocs: _.transform(def.modules, function(moduleDocs, id, alias) {
+            moduleDocs[id] = { id: alias, doc: null };
+          })
+        };
+      });
+
+      // Now add all the module docs to their corresponding type definition doc
+      _.forEach(docs, function(doc) {
+        _.forEach(typeDefDocs, function(typeDefDoc) {
+          if(typeDefDoc.moduleDocs[doc.id]) {
+            // Add a copy, because we are going to modify it
+            typeDefDoc.moduleDocs[doc.id].doc = doc;
+          }
+        });
+      });
+
+      return _.filter(typeDefDocs, function(doc) {
+        _.forEach(doc.moduleDocs, function(modDoc, alias) {
+          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) {
+
+            // Search for classes with a constructor marked as `@private`
+            if (exportDoc.docType === 'class' && exportDoc.constructorDoc && exportDoc.constructorDoc.private) {
+
+              // Convert this class to an interface with no constructor
+              exportDoc.docType = 'interface';
+              exportDoc.constructorDoc = null;
+              
+              if (exportDoc.heritage) {
+                // convert the heritage since interfaces use `extends` not `implements`
+                exportDoc.heritage = exportDoc.heritage.replace('implements', 'extends');
+              }
+
+              // Add the `declare var SomeClass extends InjectableReference` construct
+              modDoc.doc.exports.push({
+                docType: 'var',
+                name: exportDoc.name,
+                id: exportDoc.id,
+                heritage: ': InjectableReference'
+              });
+            }
+          });
+        });
+        return !!doc;
+      });
+    }
+  };
+};

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

@@ -0,0 +1,48 @@
+var mockPackage = require('../mocks/mockPackage');
+var Dgeni = require('dgeni');
+var path = require('canonical-path');
+var _ = require('lodash');
+
+describe('createTypeDefinitionFile processor', function() {
+  var dgeni, injector, processor;
+
+  beforeEach(function() {
+    dgeni = new Dgeni([mockPackage()]);
+    injector = dgeni.configureInjector();
+    processor = injector.get('createTypeDefinitionFile');
+
+    // Initialize the processor
+    processor.typeDefinitions = [{
+      id: 'angular2/angular2',
+      modules: { 'angular2/angular2': 'angular2/angular2' }
+    }];
+  });
+
+
+
+  describe('classes with private constructors', function() {
+    
+    it('should convert heritage from `implements` into `extends`', function() {
+      
+      // Create some mock docs for testing
+      var docs = [
+        {
+          id: 'angular2/angular2',
+          exports: [
+            { docType: 'class', heritage: 'implements Xyz', constructorDoc: { private: true }  }
+          ]
+        }
+      ];
+
+      docs = processor.$process(docs);
+      
+      expect(docs.length).toEqual(1);
+      expect(docs[0].docType).toEqual('type-definition');
+
+      var moduleDoc = docs[0].moduleDocs['angular2/angular2'].doc;
+      expect(moduleDoc.exports.length).toEqual(2);
+      expect(moduleDoc.exports[0].heritage).toEqual('extends Xyz');
+    });
+  });
+	
+});

scripts/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;
+}

scripts/docs/typescript-package/index.js

@@ -1,4 +1,4 @@
-require('../../tools/transpiler/index.js').init();
+//require('../../tools/transpiler/index.js').init();
 
 var basePackage = require('dgeni-packages/base');
 var Package = require('dgeni').Package;
@@ -53,7 +53,7 @@ module.exports = new Package('typescript-parsing', [basePackage])
     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';
+  var MODULES_DOCS_PATH = 'docs';
 
   computePathsProcessor.pathTemplates.push({
     docTypes: ['module'],