build(aio): add github links to API doc members (#24000)

This change adds Github edit and view links to methods and decorator options. It is possible to add these to properties also but the UI is rather tight as these are displayed in a table. PR Close #24000
2018-05-23 22:56:05 +01:00 · 2018-05-23 22:56:05 +01:00 · 39af314e29
commit 39af314e29
parent 8daadf360c
8 changed files with 51 additions and 23 deletions
--- a/aio/src/styles/2-modules/_api-pages.scss
+++ b/aio/src/styles/2-modules/_api-pages.scss
@ -1,4 +1,4 @@
-.page-actions {
+.github-links {
  float: right;
  .material-icons {
    border-radius: 4px;
@ -32,12 +32,28 @@

  .method-table, .option-table {
    th {
-      padding: 8px 16px;
+      display: flex;
+      align-items: center;
+
+      h3 {
+        flex: 1;
+      }
+
+      .github-links {
+        a {
+          color: $mediumgray;
+          .material-icons:hover {
+            background: none;
+            color: $blue;
+          }
+        }
+      }
    }

    h3 {
      margin: 6px 0;
      font-weight: bold;
+      clear: left;
    }

    h4 {
--- a/aio/tools/transforms/templates/api/base.template.html
+++ b/aio/tools/transforms/templates/api/base.template.html
@ -2,10 +2,7 @@
 {% set comma = joiner(',') %}
 {% set slash = joiner('/') %}
 <article>
-  <div class="page-actions">
-    <a href="{$ github.githubEditHref(doc, versionInfo) $}" aria-label="Suggest Edits" title="Suggest Edits"><i class="material-icons" aria-hidden="true" role="img">mode_edit</i></a>
-    <a href="{$ github.githubViewHref(doc, versionInfo) $}" aria-label="View Source" title="View Source"><i class="material-icons" aria-hidden="true" role="img">code</i></a>
-  </div>
+  {$ github.githubLinks(doc, versionInfo) $}
  <div class="breadcrumb">
    <script type="application/ld+json">
      {
--- a/aio/tools/transforms/templates/api/class.template.html
+++ b/aio/tools/transforms/templates/api/class.template.html
@ -10,14 +10,14 @@
  {% block additional %}{% endblock %}
  {% include "includes/description.html" %}
  {$ memberHelpers.renderProperties(doc.staticProperties, 'static-properties', 'static-property', 'Static Properties') $}
-  {$ memberHelpers.renderMethodDetails(doc.staticMethods, 'static-methods', 'static-method', 'Static Methods') $}
+  {$ memberHelpers.renderMethodDetails(versionInfo, doc.staticMethods, 'static-methods', 'static-method', 'Static Methods') $}
  {% if doc.constructorDoc %}
  <h2>Constructor</h2>
-  {$ memberHelpers.renderMethodDetail(doc.constructorDoc, 'constructor') $}{% endif %}
+  {$ memberHelpers.renderMethodDetail(versionInfo, doc.constructorDoc, 'constructor') $}{% endif %}

  {$ memberHelpers.renderProperties(doc.properties, 'instance-properties', 'instance-property', 'Properties') $}

-  {$ memberHelpers.renderMethodDetails(doc.methods, 'instance-methods', 'instance-method', 'Methods') $}
+  {$ memberHelpers.renderMethodDetails(versionInfo, doc.methods, 'instance-methods', 'instance-method', 'Methods') $}

  {% block annotations %}{% include "includes/annotations.html" %}{% endblock %}
 {% endblock %}
--- a/aio/tools/transforms/templates/api/decorator.template.html
+++ b/aio/tools/transforms/templates/api/decorator.template.html
@ -1,3 +1,4 @@
+{% import "lib/githubLinks.html" as github -%}
 {% import "lib/memberHelpers.html" as memberHelper -%}
 {% import "lib/paramList.html" as params -%}
 {% extends 'export-base.template.html' %}
@ -11,7 +12,10 @@
  {% for option in doc.members %}
  <a id="{$ option.anchor $}"></a>
  <table class="is-full-width option-table">
-    <thead><tr><th><h3>{$ option.name $}</h3></th></tr></thead>
+    <thead><tr><th>
+      <h3>{$ option.name $}</h3>
+      {$ github.githubLinks(option, versionInfo) $}
+    </th></tr></thead>
    <tbody>
      <tr>
        <td>
--- a/aio/tools/transforms/templates/api/includes/decorator-overview.html
+++ b/aio/tools/transforms/templates/api/includes/decorator-overview.html
@ -1,7 +1,7 @@
 {% import "lib/descendants.html" as descendants -%}

 {% macro renderOptionsTable(doc) %}
-<table class="is-full-width list-table option-table">
+<table class="is-full-width list-table option-overview">
  <thead>
    <tr><th>Option</th><th>Description</th></tr>
  </thead>
--- a/aio/tools/transforms/templates/api/interface.template.html
+++ b/aio/tools/transforms/templates/api/interface.template.html
@ -7,5 +7,5 @@
 {% block details %}
  {% include "includes/description.html" %}
  {$ memberHelper.renderProperties(doc.properties, 'instance-properties', 'instance-property', 'Properties') $}
-  {$ memberHelper.renderMethodDetails(doc.methods, 'instance-methods', 'instance-method', 'Methods') $}
+  {$ memberHelper.renderMethodDetails(versionInfo, doc.methods, 'instance-methods', 'instance-method', 'Methods') $}
 {% endblock %}
--- a/aio/tools/transforms/templates/api/lib/githubLinks.html
+++ b/aio/tools/transforms/templates/api/lib/githubLinks.html
@ -1,6 +1,6 @@
 {% macro githubViewHref(doc, versionInfo) -%}
 https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInfo.repo $}/tree/{$ versionInfo.currentVersion.isSnapshot and versionInfo.currentVersion.SHA or versionInfo.currentVersion.raw $}/packages/{$ doc.fileInfo.realProjectRelativePath $}#L{$ doc.startingLine + 1 $}-L{$ doc.endingLine + 1 $}
-{%- endmacro %}
+{%- endmacro -%}


 {% macro githubEditHref(doc, versionInfo) -%}
@ -9,4 +9,11 @@ https://github.com/{$ versionInfo.gitRepoInfo.owner $}/{$ versionInfo.gitRepoInf
  {%- elseif doc.docType === 'module' %}{$ doc.id.split('/')[0] $}
  {%- else %}...{%- endif -%}
 )%3A%20describe%20your%20change...#L{$ doc.startingLine + 1 $}-L{$ doc.endingLine + 1 $}
-{%- endmacro %}
+{%- endmacro -%}
+
+{% macro githubLinks(doc, versionInfo) -%}
+<div class="github-links">
+  <a href="{$ githubEditHref(doc, versionInfo) $}" aria-label="Suggest Edits" title="Suggest Edits"><i class="material-icons" aria-hidden="true" role="img">mode_edit</i></a>
+  <a href="{$ githubViewHref(doc, versionInfo) $}" aria-label="View Source" title="View Source"><i class="material-icons" aria-hidden="true" role="img">code</i></a>
+</div>
+{%- endmacro -%}
--- a/aio/tools/transforms/templates/api/lib/memberHelpers.html
+++ b/aio/tools/transforms/templates/api/lib/memberHelpers.html
@ -1,3 +1,4 @@
+{% import "lib/githubLinks.html" as github -%}
 {% import "lib/paramList.html" as params -%}

 {%- macro renderHeritage(exportDoc) -%}
@ -69,15 +70,18 @@
 {%- endif %}
 {%- endmacro -%}

-{%- macro renderMethodDetail(method, cssClass) -%}
+{%- macro renderMethodDetail(versionInfo, method, cssClass) -%}
 <a id="{$ method.anchor $}"></a>
 <table class="is-full-width method-table {$ cssClass $}">
-  {% if method.name !== 'constructor' %}<thead><tr><th><h3>
-    {% if method.isCallMember %}<i>call signature</i>
-    {% elseif method.isNewMember %}<i>construct signature</i>
-    {% else %}{$ method.name $}()
-    {% endif %}
-  </h3></th></tr></thead>{% endif %}
+  {% if method.name !== 'constructor' %}<thead><tr><th>
+    <h3>
+      {% if method.isCallMember %}<i>call signature</i>
+      {% elseif method.isNewMember %}<i>construct signature</i>
+      {% else %}{$ method.name $}()
+      {% endif %}
+    </h3>
+    {$ github.githubLinks(method, versionInfo) $}
+  </th></tr></thead>{% endif %}
  <tbody>
    {% if method.shortDescription %}<tr>
      <td class="short-description">
@ -133,13 +137,13 @@
 </table>
 {% endmacro -%}

-{%- macro renderMethodDetails(methods, containerClass, itemClass, headingText) -%}
+{%- macro renderMethodDetails(versionInfo, methods, containerClass, itemClass, headingText) -%}
 {% set nonInternalMethods = methods | filterByPropertyValue('internal', undefined) %}
 {% if nonInternalMethods.length %}
 <section class="{$ containerClass $}">
  <h2>{$ headingText $}</h2>
  {% for member in nonInternalMethods %}
-    {$ renderMethodDetail(member, itemClass) $}
+    {$ renderMethodDetail(versionInfo, member, itemClass) $}
  {% endfor %}
 </section>
 {% endif %}