build(aio): improve API docs layout and styling

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 %}

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 %}

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') $}

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 %}

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 %}

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>

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>

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">
+<section class="info-bar">
-  <span class="info-bar-item">
-    npm package: <code>@angular/{$ doc.moduleDoc.id $}</code>
-  </span>
 
-  {% if doc.ngModule %}
+<table class="is-full-width">
-  <span class="info-bar-item">
+<tbody>
-    NgModule: {@link {$ doc.ngModule $}}
+<tr>
-  </span>
+  <th>npm Package</th>
-  {% endif %}
+  <td><a href="https://www.npmjs.com/package/@angular/{$ doc.moduleDoc.id.split('/')[0] $}">@angular/{$ doc.moduleDoc.id.split('/')[0] $}</a></td>
-</div>
+</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>

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 %}

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 %}

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 %}