docs(badges): add badges in hero to identify doc type to viewer, and stability. Stylize var.template for new api style docs. Add stable, experimental, docsNotRequired tagdef in dgeni

public/_includes/_hero.jade

@@ -1,11 +1,25 @@
-- var textFormat = ''
+// Refer to jade.template.html and addJadeDataDocsProcessor to figure out where the context of this jade file originates
+- var textFormat = '';
 - var headerTitle = title + (typeof varType !== 'undefined' ? (': ' + varType) : '');
+- var capitalize = function capitalize(str) { return str.charAt(0).toUpperCase() + str.slice(1); }
+- var useBadges = docType || stability;
   
 if current.path[4] && current.path[3] == 'api'
   - var textFormat = 'is-standard-case'
 
 header(class="hero background-sky")
+  span(class="hero-title-with-badges" layout="row" layout-align="start center")
     h1(class="hero-title text-display-1 #{textFormat}") #{headerTitle}
+    if useBadges
+      span(class="badges")
+        if docType
+          span(class="status-badge").
+            #{capitalize(docType)}
+        if stability
+          span(layout="row" class="status-badge")
+            // badge circle is filled based on stability by matching a css selector in _hero.scss
+            span(class="status-circle status-#{stability}")
+            span Stability: #{capitalize(stability)}
 
   if subtitle
     h2.hero-subtitle.text-subhead #{subtitle}

public/resources/css/module/_example-title.scss

@@ -9,7 +9,7 @@
   background: #1976D2;
   box-shadow: none;
   // temporary hack to remove space between example title and code-example
-  margin-bottom: -18px;
+  margin-bottom: -5px;
   z-index: 1;
   position: relative;
   border-bottom-right-radius: 0;

public/resources/css/module/_hero.scss

@@ -1,15 +1,44 @@
-$hero-padding: ($unit * 10) ($unit * 6) ($unit * 5);
+$hero-padding: ($unit * 10) ($unit * 6) ($unit * 7);
 
 .hero {
   position: relative;
   padding: $hero-padding;
-  height: $unit * 8;
+  height: $unit * 10;
+
+  .hero-title-with-badges {
+    margin-bottom: $unit;
+  }
+
+  .status-circle {
+    margin-right: 4px;
+    border-radius: 50%;
+    width: 10px;
+    height: 10px;
+    display: inline-block;
+  }
+
+  // status-*, will be matched by the results in addJadeDataDocsProcessor.js, and reflect in _hero.jade
+  .status-deprecated {
+    background: #E53935;
+  }
+
+  .status-stable {
+    background: #558b2f;
+  }
+
+  .status-experimental {
+    background: #9575cd;
+  }
 
   @media handheld and (max-width: $phone-breakpoint),
   screen and (max-device-width: $phone-breakpoint),
   screen and (max-width: $tablet-breakpoint) {
     height: auto;
     padding-top: 40px;
+
+    .badges {
+      margin-top: 48px;
+    }
   }
 
   &.is-large {
@@ -24,7 +53,28 @@ $hero-padding: ($unit * 10) ($unit * 6) ($unit * 5);
     }
   }
 
+  .badges {
+    padding-left: 8px;
+
+    .status-badge {
+      color: #0143A3;
+      margin-left: 4px;
+      padding-left: 8px;
+      padding-right: 8px;
+      background-color: rgba(255,255,255,0.5);
+      border-radius: 2px;
+      line-height: 20px;
+      display: inline-block;
+    }
+  }
+
+  button {
+    // Override md-button from angular material to align language select with hero title.
+    margin: 0 !important;
+  }
+
   .hero-title {
+    display: inline; // title will be inline with badges
     text-transform: uppercase;
     margin: 0;
     opacity: .87;

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

@@ -58,12 +58,32 @@ module.exports = function addJadeDataDocsProcessor() {
           // GET DATA FOR EACH PAGE (CLASS, VARS, FUNCTIONS)
           var modulePageInfo  = _(doc.exports)
           .map(function(exportDoc) {
+
+            // STABILITY STATUS
+            // Supported tags:
+            // @stable
+            // @experimental
+            // @deprecated
+            // Default is the empty string (no badge)
+            // Do not capitalize the strings, they are intended for use in constructing a css class from _hero.scss
+            // and used in _hero.jade
+            var stability = '';
+            if (_.has(exportDoc, 'stable')) {
+              stability = 'stable';
+            } else if (_.has(exportDoc, 'experimental')) {
+              stability = 'experimental';
+            } else if (_.has(exportDoc, 'deprecated')) {
+              stability = 'deprecated';
+            }
+
             var dataDoc = {
               name: exportDoc.name + '-' + exportDoc.docType,
               title: exportDoc.name,
               docType: exportDoc.docType,
-              exportDoc: exportDoc
+              exportDoc: exportDoc,
+              stability: stability
             };
+
             if (exportDoc.symbolTypeName) dataDoc.varType = titleCase(exportDoc.symbolTypeName);
             if (exportDoc.originalModule) dataDoc.originalModule = exportDoc.originalModule;
             return dataDoc;

tools/api-builder/angular.io-package/tag-defs/docsNotRequired.js

@@ -0,0 +1,5 @@
+module.exports = function() {
+  return {
+    name: 'docsNotRequired'
+  };
+};

tools/api-builder/angular.io-package/tag-defs/experimental.js

@@ -0,0 +1,5 @@
+module.exports = function() {
+  return {
+    name: 'experimental'
+  };
+};

tools/api-builder/angular.io-package/tag-defs/index.js

@@ -2,5 +2,8 @@ module.exports = [
   require('./deprecated'),
   require('./howToUse'),
   require('./whatItDoes'),
-  require('./internal')
+  require('./internal'),
+  require('./stable'),
+  require('./experimental'),
+  require('./docsNotRequired'),
 ];

tools/api-builder/angular.io-package/tag-defs/stable.js

@@ -0,0 +1,5 @@
+module.exports = function() {
+  return {
+    name: 'stable'
+  };
+};

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

@@ -1,3 +1,4 @@
+{# Use this document to generate the _data.json files for harp.js. This acts as the link between dgeni, jade, and harp #}
 {
 {%- for item in doc.data %}
   "{$ item.name $}" : {
@@ -11,6 +12,9 @@
     {%- if item.originalModule %}
     "originalModule" : "{$ item.originalModule $}",
     {%- endif %}
+    {%- if item.stability %}
+    "stability" : "{$ item.stability $}",
+    {%- endif %}
     "docType": "{$ item.docType $}"
   }{% if not loop.last %},{% endif %}
 {% endfor -%}

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

@@ -4,20 +4,23 @@
 
 {% block body %}
 include {$ relativePath(doc.path, '_util-fns') $}
-.l-main-section
-  h2(class="variable export")
-    pre.prettyprint
+
+.div(layout="row" layout-xs="column" class="row-margin")
+  div(flex="20" flex-xs="100")
+    h2 Variable Export
+  div(flex="80" flex-xs="100")
+    pre.prettyprint.no-bg
       code.
         export {$ doc.name $}{$ returnType(doc.returnType) $}
 
-  p.location-badge.
+p.location-badge.
   exported from {@link {$ doc.moduleDoc.id $} {$doc.moduleDoc.id $} }
   defined in {$ githubViewLink(doc) $}
 
-  :marked
+:marked
 {%- if doc.notYetDocumented %}
     *Not Yet Documented*
 {% else %}
-{$ doc.description | indentForMarkdown(4) | trimBlankLines $}
+{$ doc.description | indentForMarkdown(2) | trimBlankLines $}
 {% endif -%}
 {% endblock %}