From a301dba68f945fc7f0ec0797fa027d5f6eb77520 Mon Sep 17 00:00:00 2001
From: Peter Bacon Darwin <pete@bacondarwin.com>
Date: Thu, 13 Jul 2017 13:36:51 +0100
Subject: [PATCH] build(aio): improve API docs layout and styling

---
 .../templates/api/class.template.html         |  4 +--
 .../templates/api/decorator.template.html     |  2 +-
 .../templates/api/directive.template.html     |  1 +
 .../templates/api/export-base.template.html   |  1 +
 .../templates/api/function.template.html      |  5 ++-
 .../templates/api/includes/annotations.html   |  2 +-
 .../api/includes/directive-overview.html      | 14 ++++++++
 .../templates/api/includes/info-bar.html      | 33 +++++++++++++------
 .../templates/api/interface.template.html     |  2 +-
 .../templates/api/type-alias.template.html    |  5 ++-
 .../templates/api/var.template.html           |  5 ++-
 11 files changed, 56 insertions(+), 18 deletions(-)
 create mode 100644 aio/tools/transforms/templates/api/includes/directive-overview.html

diff --git a/aio/tools/transforms/templates/api/class.template.html b/aio/tools/transforms/templates/api/class.template.html
index 0cbe9f8742..cdfc8dd17c 100644
--- a/aio/tools/transforms/templates/api/class.template.html
+++ b/aio/tools/transforms/templates/api/class.template.html
@@ -2,13 +2,13 @@
 {% import "lib/paramList.html" as params -%}
 {% extends 'export-base.template.html' -%}
 
+{% block overview %}{% include "includes/class-overview.html" %}{% endblock %}
 {% block details %}
-{% include "includes/class-overview.html" %}
 {% block additional %}{% endblock %}
 {% include "includes/description.html" %}
-{% include "includes/annotations.html" %}
 {$ memberHelpers.renderMemberDetails(doc.statics, 'static-members', 'static-member', 'Static Members') $}
 {% include "includes/constructor.html" %}
 {$ memberHelpers.renderMemberDetails(doc.members, 'instance-members', 'instance-member', 'Members') $}
+{% include "includes/annotations.html" %}
 
 {% endblock %}
diff --git a/aio/tools/transforms/templates/api/decorator.template.html b/aio/tools/transforms/templates/api/decorator.template.html
index 2460c3c4af..232b99b40d 100644
--- a/aio/tools/transforms/templates/api/decorator.template.html
+++ b/aio/tools/transforms/templates/api/decorator.template.html
@@ -2,8 +2,8 @@
 {% import "lib/paramList.html" as params -%}
 {% extends 'export-base.template.html' %}
 
+{% block overview %}{% include "includes/decorator-overview.html" %}{% endblock %}
 {% block details %}
-  {% include "includes/decorator-overview.html" %}
   {% include "includes/description.html" %}
   {$ memberHelper.renderMemberDetails(doc.members, 'metadata-members', 'metadata-member', 'Metadata Properties') $}
 {% endblock %}
diff --git a/aio/tools/transforms/templates/api/directive.template.html b/aio/tools/transforms/templates/api/directive.template.html
index b07a6ddccc..2858e9cd5b 100644
--- a/aio/tools/transforms/templates/api/directive.template.html
+++ b/aio/tools/transforms/templates/api/directive.template.html
@@ -2,6 +2,7 @@
 {% import "lib/paramList.html" as params -%}
 {% extends 'class.template.html' -%}
 
+{% block overview %}{% include "includes/directive-overview.html" %}{% endblock %}
 {% block additional -%}
   {% include "includes/selectors.html" %}
   {$ directiveHelper.renderBindings(doc.inputs, 'inputs', 'input', 'Inputs') $}
diff --git a/aio/tools/transforms/templates/api/export-base.template.html b/aio/tools/transforms/templates/api/export-base.template.html
index b1435b5c71..6b23a7e9db 100644
--- a/aio/tools/transforms/templates/api/export-base.template.html
+++ b/aio/tools/transforms/templates/api/export-base.template.html
@@ -5,6 +5,7 @@
   {% include "includes/what-it-does.html" %}
   {% include "includes/security-notes.html" %}
   {% include "includes/deprecation.html" %}
+  {% block overview %}{% endblock %}
   {% include "includes/how-to-use.html" %}
   {% block details %}{% endblock %}
 {% endblock %}
diff --git a/aio/tools/transforms/templates/api/function.template.html b/aio/tools/transforms/templates/api/function.template.html
index 5eb2d6dfb4..7af1d2bb6f 100644
--- a/aio/tools/transforms/templates/api/function.template.html
+++ b/aio/tools/transforms/templates/api/function.template.html
@@ -1,11 +1,14 @@
 {% import "lib/paramList.html" as params -%}
 {% extends 'export-base.template.html' -%}
 
-{% block details %}
+{% block overview %}
 <code-example language="ts" hideCopy="true" class="no-box api-heading">
 function {$ doc.name $}{$ params.paramList(doc.parameters) $}
 {%- if doc.type %}: {$ doc.type | escape $}{% endif %};
 </code-example>
+{% endblock %}
+
+{% block details %}
 {% include "includes/description.html" %}
 {% if doc.overloads.length %}
   <h2>Overloads</h2>{% for overload in doc.overloads %}
diff --git a/aio/tools/transforms/templates/api/includes/annotations.html b/aio/tools/transforms/templates/api/includes/annotations.html
index 478d520fd1..ec78059908 100644
--- a/aio/tools/transforms/templates/api/includes/annotations.html
+++ b/aio/tools/transforms/templates/api/includes/annotations.html
@@ -2,7 +2,7 @@
 <section class="annotations">
   <h2>Annotations</h2>
   {%- for decorator in doc.decorators %}
-    <code-example hideCopy="true">@{$ decorator.name $}{$ params.paramList(decorator.arguments) $}</code-example>
+    <code-example hideCopy="true" class="no-box api-heading">@{$ decorator.name $}{$ params.paramList(decorator.arguments) $}</code-example>
     {% if not decorator.notYetDocumented %}{$ decorator.description | marked $}{% endif %}
   {% endfor %}
 </section>
diff --git a/aio/tools/transforms/templates/api/includes/directive-overview.html b/aio/tools/transforms/templates/api/includes/directive-overview.html
new file mode 100644
index 0000000000..82c64e356a
--- /dev/null
+++ b/aio/tools/transforms/templates/api/includes/directive-overview.html
@@ -0,0 +1,14 @@
+{% import "lib/memberHelpers.html" as memberHelper -%}
+
+<section class="{$ doc.docType $}-overview">
+  <h2>Overview</h2>
+<code-example language="ts" hideCopy="true">{% for decorator in doc.decorators %}
+<a href="#annotations">@{$ decorator.name $}{$ params.paramList(decorator.arguments) $}</a>{% endfor %}
+class {$ doc.name $}{$ doc.typeParams | escape $}{$ memberHelper.renderHeritage(doc) $} {
+{%- if doc.statics.length %}{% for member in doc.statics %}{% if not member.internal %}
+  <a class="code-anchor" href="#{$ member.anchor $}">{$ memberHelper.renderMember(member, 1) $}</a>{% endif %}{% endfor %}{% endif %}
+{%- if doc.members.length %}{% for member in doc.members %}{% if not member.internal %}
+  <a class="code-anchor" href="#{$ member.anchor $}">{$ memberHelper.renderMember(member, 1) $}</a>{% endif %}{% endfor %}{% endif %}
+}
+</code-example>
+</section>
diff --git a/aio/tools/transforms/templates/api/includes/info-bar.html b/aio/tools/transforms/templates/api/includes/info-bar.html
index e58ab2e849..2170fefbc2 100644
--- a/aio/tools/transforms/templates/api/includes/info-bar.html
+++ b/aio/tools/transforms/templates/api/includes/info-bar.html
@@ -1,14 +1,27 @@
 {% import "lib/githubLinks.html" as github -%}
 
 <!-- INFO BAR -->
-<div class="info-banner api-info-bar">
-  <span class="info-bar-item">
-    npm package: <code>@angular/{$ doc.moduleDoc.id $}</code>
-  </span>
+<section class="info-bar">
 
-  {% if doc.ngModule %}
-  <span class="info-bar-item">
-    NgModule: {@link {$ doc.ngModule $}}
-  </span>
-  {% endif %}
-</div>
+<table class="is-full-width">
+<tbody>
+<tr>
+  <th>npm Package</th>
+  <td><a href="https://www.npmjs.com/package/@angular/{$ doc.moduleDoc.id.split('/')[0] $}">@angular/{$ doc.moduleDoc.id.split('/')[0] $}</a></td>
+</tr>
+<tr>
+  <th>Module</th>
+  <td><code>import { {$ doc.name $} } from <a href="{$ doc.moduleDoc.path $}">@angular/{$ doc.moduleDoc.id $}</a>;</code></td>
+</tr>
+<tr>
+  <th>Source</th>
+  <td>{$ github.githubViewLink(doc, versionInfo) $}</td>
+</tr>
+{% if doc.ngModule %}
+<tr>
+  <th>NgModule</th>
+  <td>{@link {$ doc.ngModule $}}</td>
+</tr>
+{% endif %}
+</tbody>
+</table>
diff --git a/aio/tools/transforms/templates/api/interface.template.html b/aio/tools/transforms/templates/api/interface.template.html
index 603e8a146a..e4d99bc238 100644
--- a/aio/tools/transforms/templates/api/interface.template.html
+++ b/aio/tools/transforms/templates/api/interface.template.html
@@ -2,8 +2,8 @@
 {% import "lib/memberHelpers.html" as memberHelper -%}
 {% extends 'export-base.template.html' -%}
 
+{% block overview %}{% include "includes/interface-overview.html" %}{% endblock %}
 {% block details %}
-  {% include "includes/interface-overview.html" %}
   {% include "includes/description.html" %}
   {$ memberHelper.renderMemberDetails(doc.members, 'instance-members', 'instance-member', 'Members') $}
 {% endblock %}
diff --git a/aio/tools/transforms/templates/api/type-alias.template.html b/aio/tools/transforms/templates/api/type-alias.template.html
index 05ce96bdb7..330ec5d688 100644
--- a/aio/tools/transforms/templates/api/type-alias.template.html
+++ b/aio/tools/transforms/templates/api/type-alias.template.html
@@ -1,8 +1,11 @@
 {% extends 'export-base.template.html' %}
 
-{% block details %}
+{% block overview %}
   <code-example language="ts" hideCopy="true">
   type {$ doc.name $}{% if doc.typeDefinition %} = {$ doc.typeDefinition | escape $}{% endif %};
   </code-example>
+{% endblock %}
+
+{% block details %}
   {% include "includes/description.html" %}
 {% endblock %}
diff --git a/aio/tools/transforms/templates/api/var.template.html b/aio/tools/transforms/templates/api/var.template.html
index 397c3f4a28..c8e590b96e 100644
--- a/aio/tools/transforms/templates/api/var.template.html
+++ b/aio/tools/transforms/templates/api/var.template.html
@@ -1,8 +1,11 @@
 {% extends 'export-base.template.html' %}
 
-{% block details %}
+{% block overview %}
   <code-example language="ts" hideCopy="true" class="no-box api-heading">
   const {$ doc.name $}: {$ doc.symbolTypeName or 'any' $};
   </code-example>
+{% endblock %}
+
+{% block details %}
   {% include "includes/description.html" %}
 {% endblock %}