docs: improve typedoc documentation generation (watson-developer-cloud#987)

* generated TypeDocs show top level properties for function argument

* hid interfaces and modules from Table of Contents

* fixed side bar navigation to exclude interfaces and type aliases

Author: SaltedCaramelCoffee

scripts/typedoc/generate_typedoc.sh

@@ -1,4 +1,4 @@
-./node_modules/.bin/typedoc --mode file --theme ./scripts/typedoc/theme --excludeExternals \
+./node_modules/.bin/typedoc --mode file --theme ./scripts/typedoc/theme --excludeExternals --excludePrivate --excludeProtected \
     --out ./doc ./authorization/v1.ts \
     ./discovery/v1.ts ./language-translator/v3.ts \
     ./natural-language-classifier/v1.ts ./natural-language-understanding/v1.ts \

scripts/typedoc/theme/assets/css/main.css

@@ -186,7 +186,7 @@ table { border-collapse: collapse; border-spacing: 0; }
 .col > :first-child, .col-1 > :first-child, .col-2 > :first-child, .col-3 > :first-child, .col-4 > :first-child, .col-5 > :first-child, .col-6 > :first-child, .col-7 > :first-child, .col-8 > :first-child, .col-9 > :first-child, .col-10 > :first-child, .col-11 > :first-child, .tsd-panel > :first-child, ul.tsd-descriptions > li > :first-child, .col > :first-child > :first-child, .col-1 > :first-child > :first-child, .col-2 > :first-child > :first-child, .col-3 > :first-child > :first-child, .col-4 > :first-child > :first-child, .col-5 > :first-child > :first-child, .col-6 > :first-child > :first-child, .col-7 > :first-child > :first-child, .col-8 > :first-child > :first-child, .col-9 > :first-child > :first-child, .col-10 > :first-child > :first-child, .col-11 > :first-child > :first-child, .tsd-panel > :first-child > :first-child, ul.tsd-descriptions > li > :first-child > :first-child, .col > :first-child > :first-child > :first-child, .col-1 > :first-child > :first-child > :first-child, .col-2 > :first-child > :first-child > :first-child, .col-3 > :first-child > :first-child > :first-child, .col-4 > :first-child > :first-child > :first-child, .col-5 > :first-child > :first-child > :first-child, .col-6 > :first-child > :first-child > :first-child, .col-7 > :first-child > :first-child > :first-child, .col-8 > :first-child > :first-child > :first-child, .col-9 > :first-child > :first-child > :first-child, .col-10 > :first-child > :first-child > :first-child, .col-11 > :first-child > :first-child > :first-child, .tsd-panel > :first-child > :first-child > :first-child, ul.tsd-descriptions > li > :first-child > :first-child > :first-child { margin-top: 0; }
 .col > :last-child, .col-1 > :last-child, .col-2 > :last-child, .col-3 > :last-child, .col-4 > :last-child, .col-5 > :last-child, .col-6 > :last-child, .col-7 > :last-child, .col-8 > :last-child, .col-9 > :last-child, .col-10 > :last-child, .col-11 > :last-child, .tsd-panel > :last-child, ul.tsd-descriptions > li > :last-child, .col > :last-child > :last-child, .col-1 > :last-child > :last-child, .col-2 > :last-child > :last-child, .col-3 > :last-child > :last-child, .col-4 > :last-child > :last-child, .col-5 > :last-child > :last-child, .col-6 > :last-child > :last-child, .col-7 > :last-child > :last-child, .col-8 > :last-child > :last-child, .col-9 > :last-child > :last-child, .col-10 > :last-child > :last-child, .col-11 > :last-child > :last-child, .tsd-panel > :last-child > :last-child, ul.tsd-descriptions > li > :last-child > :last-child, .col > :last-child > :last-child > :last-child, .col-1 > :last-child > :last-child > :last-child, .col-2 > :last-child > :last-child > :last-child, .col-3 > :last-child > :last-child > :last-child, .col-4 > :last-child > :last-child > :last-child, .col-5 > :last-child > :last-child > :last-child, .col-6 > :last-child > :last-child > :last-child, .col-7 > :last-child > :last-child > :last-child, .col-8 > :last-child > :last-child > :last-child, .col-9 > :last-child > :last-child > :last-child, .col-10 > :last-child > :last-child > :last-child, .col-11 > :last-child > :last-child > :last-child, .tsd-panel > :last-child > :last-child > :last-child, ul.tsd-descriptions > li > :last-child > :last-child > :last-child { margin-bottom: 0; }
 
-.container { max-width: 1200px; margin: 0 auto; padding: 0 40px; }
+.container { margin: 0 auto; padding: 0 40px; }
 @media (max-width: 640px) { .container { padding: 0 20px; } }
 
 .container-main { padding-bottom: 200px; }

scripts/typedoc/theme/helpers/excluded-index-section.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function excludedIndexSection(sectionTitle) {
+    // Returns true if section is excluded. Returns false otherwise
+    const excludedSections = ['Interfaces', 'Type aliases', 'Modules']
+    return excludedSections.includes(sectionTitle)
+}
+exports.excludedIndexSection = excludedIndexSection;

scripts/typedoc/theme/helpers/excluded-nav-url.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function excludedNavUrl(cssString, currentlySelected=false) {
+    // We do not want to clutter documentation with interfaces, Type aliases and Modules
+    // So we'll hide navigation links to those documentations
+    // This function will identify a url by its CSS class
+
+    // We will make an exception for when excluded items are selected
+    // In that case, we do render the selected excluded URL in the side navigation
+    // Regardless of its other css properties
+
+    // Returns true to exclude something, return false otherwise
+
+    if (currentlySelected) {
+        // We do not want to exclude selected items
+        return false
+    } else {
+        const excludedCssClasses = ['tsd-kind-interface', 'tsd-kind-type-alias']
+        const cssClasses = cssString.split(' ')
+
+        return cssClasses.some((cssClass) => {
+            return excludedCssClasses.includes(cssClass)
+        })
+    }
+}
+exports.excludedNavUrl = excludedNavUrl;

scripts/typedoc/theme/layouts/default.hbs

@@ -15,10 +15,10 @@
 
 <div class="container container-main">
     <div class="row">
-        <div class="col-8 col-content">
+        <div class="col-9 col-content">
             {{{contents}}}
         </div>
-        <div class="col-4 col-menu menu-sticky-wrap menu-highlight">
+        <div class="col-3 col-menu menu-sticky-wrap menu-highlight">
             <nav class="tsd-navigation primary">
                 <ul>
                     {{#each navigation.children}}

scripts/typedoc/theme/partials/index.hbs

@@ -4,6 +4,8 @@
     <section class="tsd-panel tsd-index-panel">
         <div class="tsd-index-content">
             {{#each groups}}
+            <!-- Unless the section is part of the exclusion list, render them -->
+            {{#unless (excludedIndexSection this.title)}}
                 <section class="tsd-index-section {{cssClasses}}">
                     <h3>{{title}}</h3>
                     <ul class="tsd-index-list">
@@ -12,6 +14,7 @@
                         {{/each}}
                     </ul>
                 </section>
+            {{/unless}}
             {{/each}}
         </div>
     </section>

scripts/typedoc/theme/partials/member.signature.body.hbs

@@ -11,34 +11,69 @@
 
 {{#if parameters}}
     <h4 class="tsd-parameters-title">Parameters</h4>
-    <ul class="tsd-parameters">
-        {{#each parameters}}
-            <li>
-                <h5>{{#compact}}
-                    {{#each flags}}
-                        <span class="tsd-flag ts-flag{{this}}">{{this}}</span>&nbsp;
-                    {{/each}}
-                    {{#if flags.isRest}}<span class="tsd-signature-symbol">...</span>{{/if}}
-                    {{name}}:&nbsp;
-                    {{#with type}}{{>type}}{{/with}}
-                    {{#if defaultValue}}
-                        <span class="tsd-signature-symbol">
-                        &nbsp;=&nbsp;
-                        {{defaultValue}}
-                        </span>
-                    {{/if}}
-                {{/compact}}</h5>
+    <table class="params">
+        <thead>
+        <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Attribute</th>
+            <th class="last">Description</th>
+        </tr>
+        </thead>
+        <tbody>
+            {{#each parameters}}
+                <tr>
+                    <td><code>{{name}}</code></td>
+                    <td>{{#with type}}{{>type}}{{/with}}</td>
+                    <td>{{this.flags}}</td>
+                    <td>
+                        <p>{{comment.text}}</p>
+                        <p>{{comment.shortText}}</p>
+                        {{#with type.reflection.children}}
+                        {{#if this}}
+                        <h4>Properties</h4>
+                        <table>
+                            <thead>
+                                <tr>
+                                    <th>Name</th>
+                                    <th>Type</th>
+                                    <th>Attributes</th>
+                                    <th>Description</th>
+                                </tr>
+                            </thead>
+                            <tbody>
+                            <!-- Print out all required parameters-->
+                            {{#each this}}
+                            {{#unless this.flags}}
+                                <tr>
+                                    <td><code>{{name}}</code></td>
+                                    <td>{{#with type}}{{>type}}{{/with}}</td>
+                                    <td>{{flags}}</td>
+                                    <td>{{comment.shortText}}</td>
+                                </tr>
+                            {{/unless}}
+                            {{/each}}
 
-                {{> comment}}
-
-                {{#if type.declaration}}
-                    {{#with type.declaration}}
-                        {{> parameter}}
-                    {{/with}}
-                {{/if}}
-            </li>
-        {{/each}}
-    </ul>
+                            <!-- Print out all optional parameters-->
+                            {{#each this}}
+                            {{#if this.flags}}
+                            <tr>
+                                <td><code>{{name}}</code></td>
+                                <td>{{#with type}}{{>type}}{{/with}}</td>
+                                <td>{{flags}}</td>
+                                <td>{{comment.shortText}}</td>
+                            </tr>
+                            {{/if}}
+                            {{/each}}
+                            </tbody>
+                        </table>
+                        {{/if}}
+                        {{/with}}
+                    </td>
+                </tr>
+            {{/each}}
+        </tbody>
+    </table>
 {{/if}}
 
 {{#if type}}

scripts/typedoc/theme/partials/members.group.hbs

@@ -1,3 +1,4 @@
+{{#unless (excludedIndexSection this.title)}}
 <section class="tsd-panel-group tsd-member-group {{cssClasses}}">
     <h2>{{title}}</h2>
     {{#each children}}
@@ -6,3 +7,4 @@
         {{/unless}}
     {{/each}}
 </section>
+{{/unless}}

scripts/typedoc/theme/partials/toc.hbs

@@ -1,3 +1,5 @@
+<!-- Unless the url is part of the exclusion list, render them -->
+{{#unless (excludedNavUrl this.cssClasses isInPath)}}
 <li class="{{#if isInPath}}current{{/if}} {{cssClasses}}">
     <a href="{{relativeURL url}}" class="tsd-kind-icon">{{{wbr title}}}</a>
     {{#if children}}
@@ -8,3 +10,4 @@
         </ul>
     {{/if}}
 </li>
+{{/unless}}

scripts/typedoc/theme/partials/toc.root.hbs

@@ -2,6 +2,8 @@
     </ul>
     <ul class="current">
 {{/if}}
+<!-- Unless the url is part of the exclusion list, render them -->
+{{#unless (excludedNavUrl this.cssClasses isInPath)}}
 <li class="{{#if isInPath}}current{{/if}} {{cssClasses}}">
     <a href="{{relativeURL url}}" class="tsd-kind-icon">{{{wbr title}}}</a>
     {{#if children}}
@@ -12,6 +14,7 @@
         </ul>
     {{/if}}
 </li>
+{{/unless}}
 {{#if isInPath}}
     </ul>
     <ul class="after-current">