feat(api docs): use partials for api docs. Implement deprecated and security notes section

Author: Eric Jimenez

tools/api-builder/angular.io-package/processors/addJadeDataDocsProcessor.js

@@ -74,6 +74,7 @@ module.exports = function addJadeDataDocsProcessor() {
               stability = 'experimental';
             } else if (_.has(exportDoc, 'deprecated')) {
               stability = 'deprecated';
+              exportDoc.showDeprecatedNotes = true;
             }
 
             var howToUse = '';
@@ -102,7 +103,14 @@ module.exports = function addJadeDataDocsProcessor() {
             // Default is no security risk assessed for api
             var security = false;
             if (_.has(exportDoc, 'security')) {
-              security = true;
+              var securityArray = exportDoc.tags.tags.filter(function(tag) {
+                return tag.tagName === 'security'
+              });
+
+              // Remove line breaks, there should only be one tag
+              security = securityArray[0].description.replace(/(\r\n|\n|\r)/gm,"");
+
+              exportDoc.showSecurityNotes = true;
             }
 
             // Data inserted into jade-data.template.html

tools/api-builder/angular.io-package/templates/class.template.html

@@ -5,36 +5,22 @@
 {% block body %}
 include {$ relativePath(doc.path, '_util-fns') $}
 
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
-  div(flex="20" flex-xs="100")
-    h2(class="h2-api-docs") What it does
-  div(flex="80" flex-xs="100")
-    :marked
-    {%- if doc.whatItDoes %}
-{$ doc.whatItDoes | indentForMarkdown(6) $}
-    {% else %}
-      *Not yet documented*
-    {% endif %}
+{% include "layout/_what-it-does.html" %}
 
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
-  div(flex="20" flex-xs="100")
-    h2(class="h2-api-docs") How to use
-  div(flex="80" flex-xs="100")
-    :marked
-    {%- if doc.howToUse %}
-{$ doc.howToUse | indentForMarkdown(6) $}
-    {% else %}
-      *Not yet documented*
-    {% endif %}
+{% include "layout/_security-notes.html" %}
+
+{% include "layout/_deprecated-notes.html" %}
+
+{% include "layout/_how-to-use.html" %}
 
-.div(layout="row" layout-xs="column" class="ng-cloak")
+div(layout="row" layout-xs="column" class="ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Class Overview
   div(flex="80" flex-xs="100")
     code(class="no-bg api-doc-code openParens") class {$ doc.name $} {
 
     {% if doc.statics.length %}
-    .div(layout="column")
+    div(layout="column")
       {% for member in doc.statics %}{% if not member.internal %}
         pre(class="prettyprint no-bg-with-indent")
           a(class="code-anchor" href="#{$ member.name $}-anchor")
@@ -43,14 +29,14 @@
       {% endif %}{% endfor %}
     {% endif %}
     {% if doc.constructorDoc.name %}
-    .div(layout="column")
+    div(layout="column")
       pre(class="prettyprint no-bg-with-indent")
         a(class="code-anchor" href="#constructor")
           code(class="code-background api-doc-code") {$ doc.constructorDoc.name $}
         code(class="api-doc-code") {$ paramList(doc.constructorDoc.parameters) | indent(8, false) | trim $}
     {% endif %}
     {% if doc.members.length %}
-    .div(layout="column")
+    div(layout="column")
       {% for member in doc.members %}{% if not member.internal %}
         pre(class="prettyprint no-bg-with-indent")
           a(class="code-anchor" href="#{$ member.name $}-anchor")
@@ -64,7 +50,7 @@
 {% block additional %}
 {% endblock %}
 
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Class Description
   div(class="code-links" flex="80" flex-xs="100")
@@ -73,7 +59,7 @@
 {$ doc.description | indentForMarkdown(6) | trimBlankLines $}
     {% endif %}
 
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Class Export
   div(flex="80" flex-xs="100")
@@ -83,7 +69,7 @@
 
 {%- if doc.decorators.length %}
 {% block annotations %}
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Annotations
   div(flex="80" flex-xs="100")
@@ -100,7 +86,7 @@
 {% endif %}
 
 {%- if doc.constructorDoc and not doc.constructorDoc.internal %}
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Constructor
   div(flex="80" flex-xs="100")
@@ -115,7 +101,7 @@
 {% endif %}
 
 {% if doc.statics.length %}
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Static Members
   div(class="code-links" flex="80" flex-xs="100")
@@ -137,7 +123,7 @@
 {% endif %}
 
 {% if doc.members.length %}
-.div(layout="row" layout-xs="column" class="instance-members" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="instance-members" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Class Details
   div(class="code-links" flex="80" flex-xs="100")

tools/api-builder/angular.io-package/templates/decorator.template.html

@@ -5,7 +5,15 @@
 {% block body %}
 include {$ relativePath(doc.path, '_util-fns') $}
 
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+{% include "layout/_what-it-does.html" %}
+
+{% include "layout/_security-notes.html" %}
+
+{% include "layout/_deprecated-notes.html" %}
+
+{% include "layout/_how-to-use.html" %}
+
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Variable Export
   div(class="code-links" flex="80" flex-xs="100")

tools/api-builder/angular.io-package/templates/directive.template.html

@@ -8,7 +8,7 @@
 {% block additional -%}
 
 {%- if doc.directiveOptions.selector.split(',').length %}
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Selectors
   div(flex="80" flex-xs="100")
@@ -19,7 +19,7 @@
 {% endif %}
 
 {% if doc.outputs %}
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Outputs
   div(flex="80" flex-xs="100")
@@ -34,7 +34,7 @@
 {% endif %}
 
 {% if doc.inputs %}
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Inputs
   div(flex="80" flex-xs="100")
@@ -49,7 +49,7 @@
 {% endif %}
 
 {%- if doc.directiveOptions.exportAs %}
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Exported as
   div(flex="80" flex-xs="100")

tools/api-builder/angular.io-package/templates/function.template.html

@@ -5,7 +5,15 @@
 {% block body %}
 include {$ relativePath(doc.path, '_util-fns') $}
 
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+{% include "layout/_what-it-does.html" %}
+
+{% include "layout/_security-notes.html" %}
+
+{% include "layout/_deprecated-notes.html" %}
+
+{% include "layout/_how-to-use.html" %}
+
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Class Export
   div(class="code-links" flex="80" flex-xs="100")

tools/api-builder/angular.io-package/templates/layout/_deprecated-notes.html

@@ -0,0 +1,12 @@
+{% if doc.showDeprecatedNotes %}
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+  div(flex="20" flex-xs="100")
+    h2(class="h2-api-docs") Deprecation Notes
+  div(flex="80" flex-xs="100")
+    :marked
+    {%- if doc.deprecated %}
+{$ doc.deprecated | indentForMarkdown(6) $}
+    {% else %}
+      *Not yet documented*
+    {% endif %}
+{% endif %}

tools/api-builder/angular.io-package/templates/layout/_how-to-use.html

@@ -0,0 +1,10 @@
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+  div(flex="20" flex-xs="100")
+    h2(class="h2-api-docs") How to use
+  div(flex="80" flex-xs="100")
+    :marked
+    {%- if doc.howToUse %}
+{$ doc.howToUse | indentForMarkdown(6) $}
+    {% else %}
+      *Not yet documented*
+    {% endif %}

tools/api-builder/angular.io-package/templates/layout/_security-notes.html

@@ -0,0 +1,8 @@
+{% if doc.showSecurityNotes and doc.security %}
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+  div(flex="20" flex-xs="100")
+    h2(class="h2-api-docs") Security Risk
+  div(flex="80" flex-xs="100")
+    :marked
+{$ doc.security | indentForMarkdown(6) $}
+{% endif %}

tools/api-builder/angular.io-package/templates/layout/_what-it-does.html

@@ -0,0 +1,10 @@
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+  div(flex="20" flex-xs="100")
+    h2(class="h2-api-docs") What it does
+  div(flex="80" flex-xs="100")
+    :marked
+    {%- if doc.whatItDoes %}
+{$ doc.whatItDoes | indentForMarkdown(6) $}
+    {% else %}
+      *Not yet documented*
+    {% endif %}

tools/api-builder/angular.io-package/templates/var.template.html

@@ -5,7 +5,15 @@
 {% block body %}
 include {$ relativePath(doc.path, '_util-fns') $}
 
-.div(layout="row" layout-xs="column" class="row-margin ng-cloak")
+{% include "layout/_what-it-does.html" %}
+
+{% include "layout/_security-notes.html" %}
+
+{% include "layout/_deprecated-notes.html" %}
+
+{% include "layout/_how-to-use.html" %}
+
+div(layout="row" layout-xs="column" class="row-margin ng-cloak")
   div(flex="20" flex-xs="100")
     h2(class="h2-api-docs") Variable Export
   div(class="code-links" flex="80" flex-xs="100")