Skip to content

Commit 6bb1052

Browse files
SaltedCaramelCoffeeSaltedCaramelCoffee
authored
docs: improve typedoc documentation generation (#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
1 parent 7bc6341 commit 6bb1052

10 files changed

Lines changed: 111 additions & 31 deletions

File tree

‎scripts/typedoc/generate_typedoc.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
./node_modules/.bin/typedoc --mode file --theme ./scripts/typedoc/theme --excludeExternals \
1+
./node_modules/.bin/typedoc --mode file --theme ./scripts/typedoc/theme --excludeExternals --excludePrivate --excludeProtected \
22
--out ./doc ./authorization/v1.ts \
33
./discovery/v1.ts ./language-translator/v3.ts \
44
./natural-language-classifier/v1.ts ./natural-language-understanding/v1.ts \

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ table { border-collapse: collapse; border-spacing: 0; }
186186
.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; }
187187
.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; }
188188

189-
.container { max-width: 1200px; margin: 0 auto; padding: 0 40px; }
189+
.container { margin: 0 auto; padding: 0 40px; }
190190
@media (max-width: 640px) { .container { padding: 0 20px; } }
191191

192192
.container-main { padding-bottom: 200px; }

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

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
"use strict";
2+
Object.defineProperty(exports, "__esModule", { value: true });
3+
function excludedIndexSection(sectionTitle) {
4+
// Returns true if section is excluded. Returns false otherwise
5+
const excludedSections = ['Interfaces', 'Type aliases', 'Modules']
6+
return excludedSections.includes(sectionTitle)
7+
}
8+
exports.excludedIndexSection = excludedIndexSection;

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

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
"use strict";
2+
Object.defineProperty(exports, "__esModule", { value: true });
3+
function excludedNavUrl(cssString, currentlySelected=false) {
4+
// We do not want to clutter documentation with interfaces, Type aliases and Modules
5+
// So we'll hide navigation links to those documentations
6+
// This function will identify a url by its CSS class
7+
8+
// We will make an exception for when excluded items are selected
9+
// In that case, we do render the selected excluded URL in the side navigation
10+
// Regardless of its other css properties
11+
12+
// Returns true to exclude something, return false otherwise
13+
14+
if (currentlySelected) {
15+
// We do not want to exclude selected items
16+
return false
17+
} else {
18+
const excludedCssClasses = ['tsd-kind-interface', 'tsd-kind-type-alias']
19+
const cssClasses = cssString.split(' ')
20+
21+
return cssClasses.some((cssClass) => {
22+
return excludedCssClasses.includes(cssClass)
23+
})
24+
}
25+
}
26+
exports.excludedNavUrl = excludedNavUrl;

‎scripts/typedoc/theme/layouts/default.hbs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,10 @@
1515

1616
<div class="container container-main">
1717
<div class="row">
18-
<div class="col-8 col-content">
18+
<div class="col-9 col-content">
1919
{{{contents}}}
2020
</div>
21-
<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
21+
<div class="col-3 col-menu menu-sticky-wrap menu-highlight">
2222
<nav class="tsd-navigation primary">
2323
<ul>
2424
{{#each navigation.children}}

‎scripts/typedoc/theme/partials/index.hbs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
<section class="tsd-panel tsd-index-panel">
55
<div class="tsd-index-content">
66
{{#each groups}}
7+
<!-- Unless the section is part of the exclusion list, render them -->
8+
{{#unless (excludedIndexSection this.title)}}
79
<section class="tsd-index-section {{cssClasses}}">
810
<h3>{{title}}</h3>
911
<ul class="tsd-index-list">
@@ -12,6 +14,7 @@
1214
{{/each}}
1315
</ul>
1416
</section>
17+
{{/unless}}
1518
{{/each}}
1619
</div>
1720
</section>

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

Lines changed: 62 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -11,34 +11,69 @@
1111

1212
{{#if parameters}}
1313
<h4 class="tsd-parameters-title">Parameters</h4>
14-
<ul class="tsd-parameters">
15-
{{#each parameters}}
16-
<li>
17-
<h5>{{#compact}}
18-
{{#each flags}}
19-
<span class="tsd-flag ts-flag{{this}}">{{this}}</span>&nbsp;
20-
{{/each}}
21-
{{#if flags.isRest}}<span class="tsd-signature-symbol">...</span>{{/if}}
22-
{{name}}:&nbsp;
23-
{{#with type}}{{>type}}{{/with}}
24-
{{#if defaultValue}}
25-
<span class="tsd-signature-symbol">
26-
&nbsp;=&nbsp;
27-
{{defaultValue}}
28-
</span>
29-
{{/if}}
30-
{{/compact}}</h5>
14+
<table class="params">
15+
<thead>
16+
<tr>
17+
<th>Name</th>
18+
<th>Type</th>
19+
<th>Attribute</th>
20+
<th class="last">Description</th>
21+
</tr>
22+
</thead>
23+
<tbody>
24+
{{#each parameters}}
25+
<tr>
26+
<td><code>{{name}}</code></td>
27+
<td>{{#with type}}{{>type}}{{/with}}</td>
28+
<td>{{this.flags}}</td>
29+
<td>
30+
<p>{{comment.text}}</p>
31+
<p>{{comment.shortText}}</p>
32+
{{#with type.reflection.children}}
33+
{{#if this}}
34+
<h4>Properties</h4>
35+
<table>
36+
<thead>
37+
<tr>
38+
<th>Name</th>
39+
<th>Type</th>
40+
<th>Attributes</th>
41+
<th>Description</th>
42+
</tr>
43+
</thead>
44+
<tbody>
45+
<!-- Print out all required parameters-->
46+
{{#each this}}
47+
{{#unless this.flags}}
48+
<tr>
49+
<td><code>{{name}}</code></td>
50+
<td>{{#with type}}{{>type}}{{/with}}</td>
51+
<td>{{flags}}</td>
52+
<td>{{comment.shortText}}</td>
53+
</tr>
54+
{{/unless}}
55+
{{/each}}
3156

32-
{{> comment}}
33-
34-
{{#if type.declaration}}
35-
{{#with type.declaration}}
36-
{{> parameter}}
37-
{{/with}}
38-
{{/if}}
39-
</li>
40-
{{/each}}
41-
</ul>
57+
<!-- Print out all optional parameters-->
58+
{{#each this}}
59+
{{#if this.flags}}
60+
<tr>
61+
<td><code>{{name}}</code></td>
62+
<td>{{#with type}}{{>type}}{{/with}}</td>
63+
<td>{{flags}}</td>
64+
<td>{{comment.shortText}}</td>
65+
</tr>
66+
{{/if}}
67+
{{/each}}
68+
</tbody>
69+
</table>
70+
{{/if}}
71+
{{/with}}
72+
</td>
73+
</tr>
74+
{{/each}}
75+
</tbody>
76+
</table>
4277
{{/if}}
4378

4479
{{#if type}}

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
{{#unless (excludedIndexSection this.title)}}
12
<section class="tsd-panel-group tsd-member-group {{cssClasses}}">
23
<h2>{{title}}</h2>
34
{{#each children}}
@@ -6,3 +7,4 @@
67
{{/unless}}
78
{{/each}}
89
</section>
10+
{{/unless}}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
<!-- Unless the url is part of the exclusion list, render them -->
2+
{{#unless (excludedNavUrl this.cssClasses isInPath)}}
13
<li class="{{#if isInPath}}current{{/if}} {{cssClasses}}">
24
<a href="{{relativeURL url}}" class="tsd-kind-icon">{{{wbr title}}}</a>
35
{{#if children}}
@@ -8,3 +10,4 @@
810
</ul>
911
{{/if}}
1012
</li>
13+
{{/unless}}

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

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
</ul>
33
<ul class="current">
44
{{/if}}
5+
<!-- Unless the url is part of the exclusion list, render them -->
6+
{{#unless (excludedNavUrl this.cssClasses isInPath)}}
57
<li class="{{#if isInPath}}current{{/if}} {{cssClasses}}">
68
<a href="{{relativeURL url}}" class="tsd-kind-icon">{{{wbr title}}}</a>
79
{{#if children}}
@@ -12,6 +14,7 @@
1214
</ul>
1315
{{/if}}
1416
</li>
17+
{{/unless}}
1518
{{#if isInPath}}
1619
</ul>
1720
<ul class="after-current">

0 commit comments

Comments
 (0)