chore(doc-gen): generate docs for angular.io

You can generate docs for comsumption by the angular.io website by running:

```bash
gulp docs/angular.io
```

The generated docs can be found in `dist/angular.io`

docs/angular.io-package/index.js

@@ -0,0 +1,48 @@
+var path = require('canonical-path');
+var Package = require('dgeni').Package;
+var basePackage = require('../public-docs-package');
+
+var PARTIAL_PATH = 'partials';
+var MODULES_DOCS_PATH = PARTIAL_PATH + '/api';
+
+module.exports = new Package('angular.io', [basePackage])
+
+.factory(require('./services/renderMarkdown'))
+.processor(require('./processors/addJadeDataDocsProcessor'))
+
+// Configure rendering
+.config(function(templateFinder, templateEngine) {
+
+  templateFinder.templateFolders
+      .unshift(path.resolve(__dirname, 'templates'));
+})
+
+.config(function(writeFilesProcessor) {
+  writeFilesProcessor.outputFolder  = 'dist/angular.io';
+})
+
+
+.config(function(computeIdsProcessor, computePathsProcessor, EXPORT_DOC_TYPES) {
+
+  computePathsProcessor.pathTemplates.push({
+    docTypes: ['module'],
+    pathTemplate: '${id}.html',
+    outputPathTemplate: MODULES_DOCS_PATH + '/${id}/index.jade'
+  });
+
+  computePathsProcessor.pathTemplates.push({
+    docTypes: EXPORT_DOC_TYPES,
+    pathTemplate: '${moduleDoc.id}/${name}-${docType}.html',
+    outputPathTemplate: MODULES_DOCS_PATH + '/${moduleDoc.id}/${name}-${docType}.jade',
+  });
+
+  computePathsProcessor.pathTemplates.push({
+    docTypes: ['jade-data'],
+    pathTemplate: '${originalDoc.id}/_data',
+    outputPathTemplate: MODULES_DOCS_PATH + '/${path}.json'
+  });
+})
+
+.config(function(getLinkInfo) {
+  getLinkInfo.relativeLinks = true;
+});

docs/angular.io-package/processors/addJadeDataDocsProcessor.js

@@ -0,0 +1,75 @@
+var _ = require('lodash');
+var path = require('canonical-path');
+
+var titleCase = function(text) {
+  return text.replace(/(.)(.*)/, function(_, first, rest) {
+    return first.toUpperCase() + rest;
+  });
+};
+
+/*
+* Create _data.json file for Harp pages
+*
+* http://harpjs.com/docs/development/metadata
+*
+* This method creates the meta data required for each page
+* such as the title, description, etc. This meta data is used
+* in the harp static site generator to create the title for headers
+* and the navigation used in the API docs
+*
+*/
+
+module.exports = function addJadeDataDocsProcessor(EXPORT_DOC_TYPES) {
+  return {
+    $runAfter: ['adding-extra-docs', 'cloneExportedFromDocs'],
+    $runBefore: ['extra-docs-added'],
+    $process: function(docs) {
+      var extraDocs = [];
+      var modules = [];
+
+
+      /*
+      * Create Data for Modules
+      *
+      * Modules must be public and have content
+      */
+
+      _.forEach(docs, function(doc) {
+        if (doc.docType === 'module' && doc.exports.length) {
+          modules.push(doc);
+
+          // GET DATA FOR INDEX PAGE OF MODULE SECTION
+          var indexPageInfo = [{
+            name: 'index',
+            title: _.map(path.basename(doc.fileInfo.baseName).split('_'), function(part) {
+              return titleCase(part);
+            }).join(' '),
+            intro: doc.description.replace('"', '\"').replace(/\r?\n|\r/g,"")
+          }];
+
+          // GET DATA FOR EACH PAGE (CLASS, VARS, FUNCTIONS)
+          var modulePageInfo  = _.map(doc.exports, function(exportDoc) {
+            return {
+              name: exportDoc.name + '-' + exportDoc.docType,
+              title: exportDoc.name + ' ' + titleCase(exportDoc.docType)
+            };
+          });
+
+          //COMBINE PAGE DATA
+          var allPageData = indexPageInfo.concat(modulePageInfo);
+
+          // PUSH DATA TO EXTRA DOCS ARRAY
+          extraDocs.push({
+            id: doc.id + "-data",
+            docType: 'jade-data',
+            originalDoc: doc,
+            data: allPageData
+          });
+        }
+      });
+
+
+      return docs.concat(extraDocs);
+    }
+  };
+};

docs/angular.io-package/services/renderMarkdown.js

@@ -0,0 +1,52 @@
+var marked = require('marked');
+var Encoder = require('node-html-encoder').Encoder;
+var html2jade = require('html2jade');
+var indentString = require('indent-string');
+var S = require('string');
+
+// entity type encoder
+var encoder = new Encoder('entity');
+
+
+
+/**
+ * @dgService renderMarkdown
+ * @description
+ * Render the markdown in the given string as HTML.
+ */
+module.exports = function renderMarkdown(trimIndentation) {
+
+  var renderer = new marked.Renderer();
+
+  renderer.code = function(code, lang, escaped) {
+
+    var cssClasses = ['prettyprint', 'linenums'];
+    var trimmedCode = trimIndentation(code);
+
+    if(lang) {
+      if(lang=='html') {
+        trimmedCode = encoder.htmlEncode(trimmedCode);
+      }
+      cssClasses.push(this.options.langPrefix + escape(lang, true));
+    }
+
+    return 'pre(class="' + cssClasses.join(' ') + '")\n'
+            + indentString('code.\n', ' ', 2)
+            + trimmedCode;
+  };
+
+  renderer.heading = function (text, level, raw) {
+    var headingText = marked.Renderer.prototype.heading.call(renderer, text, level, raw);
+    var title = 'h2 ' + S(headingText).stripTags().s;
+
+    if (level==2) {
+      title = '.l-main-section\n' + indentString(title, ' ', 2) ;
+    }
+
+    return title;
+  };
+
+  return function(content) {
+    return marked(content, { renderer: renderer });
+  };
+};

docs/angular.io-package/templates/class.template.html

@@ -0,0 +1,48 @@
+{% include "lib/paramList.html" -%}
+{% extends 'layout/base.template.html' -%}
+
+{% block body %}
+p.location-badge.
+  exported from <a href="/{$ doc.moduleDoc.path $}">{$ doc.moduleDoc.id $}</a>
+  defined in <a href="https://github.com/angular/angular/tree/master/modules/{$ doc.location.start.source.name $}.js#L{$ doc.location.start.line $}">{$ doc.location.start.source.name $}.js (line {$ doc.location.start.line $})</a>
+
+:markdown
+{$ doc.description | indent(2, true) $}
+
+{%- if doc.constructorDoc or doc.members.length -%}
+.l-main-section
+  h2 Members
+
+{%- if doc.constructorDoc %}
+  .l-sub-section
+    h3 {$ doc.constructorDoc.name $}
+
+    {% if doc.constructorDoc.params %}
+    pre.prettyprint
+      code.
+        {$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.params) | indent(4, true) | trim $}
+    {% endif %}
+    :markdown
+{$ doc.constructorDoc.description | indent(6, true) | replace('## Example', '') | replace('# Example', '') $}
+
+
+{% endif -%}
+
+{%- for member in doc.members %}
+  .l-sub-section
+    h3 {$ member.name $}
+
+    {% if member.params %}
+    pre.prettyprint
+      code.
+        {$ member.name $}{$ paramList(member.params) | indent(4, true) | trim $}
+    {% endif %}
+    :markdown
+{$ member.description | indent(6, true) | replace('## Example', '') | replace('# Example', '')  $}
+
+
+
+{% endfor %}
+{%- endif -%}
+
+{% endblock %}

docs/angular.io-package/templates/function.template.html

@@ -0,0 +1,16 @@
+{% include "lib/paramList.html" -%}
+{% extends 'layout/base.template.html' -%}
+
+{% block body %}
+.l-main-section
+  h2(class="function export") {$ doc.name $}
+
+  p <code>{$ paramList(doc.parameters) $}</code>
+
+  p.location-badge.
+    exported from <a href="/{$ doc.moduleDoc.path $}">{$ doc.moduleDoc.id $}</a>
+
+  :markdown
+{$ doc.description | indent(4, true) $}
+
+{% endblock %}

docs/angular.io-package/templates/jade-data.template.html

@@ -0,0 +1,8 @@
+{
+{%- for item in doc.data %}
+  "{$ item.name $}" : {
+    "title" : "{$ item.title $}"{% if item.intro %},
+    "intro" : "{$ item.intro $}"{% endif %}
+  }{% if not loop.last %},{% endif %}
+{% endfor -%}
+}

docs/angular.io-package/templates/layout/base.template.html

@@ -0,0 +1 @@
+{% block body %}{% endblock %}

docs/angular.io-package/templates/lib/paramList.html

@@ -0,0 +1,7 @@
+{% macro paramList(params) -%}
+  {%- if params -%}
+    ({%- for param in params -%}
+      {$ param | escape $}{% if not loop.last %}, {% endif %}
+    {%- endfor %})
+  {%- endif %}
+{%- endmacro -%}

docs/angular.io-package/templates/module.template.html

@@ -0,0 +1,11 @@
+{% extends 'layout/base.template.html' -%}
+{% block body -%}
+ul
+  for page, slug in public.docs[current.path[1]][current.path[2]][current.path[3]][current.path[4]]._data
+    if slug != 'index'
+      url = "/docs/" + current.path[1] + "/" + current.path[2] + "/" + current.path[3] + "/" + current.path[4] + "/" + slug + ".html"
+
+      li.c8
+        != partial("../../../../../_includes/_hover-card", {name: page.title, url: url })
+
+{% endblock %}

docs/angular.io-package/templates/var.template.html

@@ -0,0 +1,11 @@
+{% extends 'layout/base.template.html' %}
+
+{% block body %}
+.l-main-section
+  h2 {$ doc.name $} <span class="type">variable</span>
+  p.location-badge.
+    exported from <a href="/{$ doc.moduleDoc.path $}">{$ doc.moduleDoc.id $}</a>
+
+  :markdown
+{$ doc.description | indent(4, true) $}
+{% endblock %}