Skip to content

Commit

Permalink
docs: make api reference landing prettier (aws#1727)
Browse files Browse the repository at this point in the history
* feat(client-documentation-generator): skip too long navigation

* docs: update typedoc plugins dependencies

* docs(core-packages-documentation-generator): update landing page navigation
  • Loading branch information
AllanZhengYP authored Nov 30, 2020
1 parent 6437e24 commit e6b2ae1
Show file tree
Hide file tree
Showing 7 changed files with 88 additions and 49 deletions.
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -115,4 +115,4 @@
],
"**/*.{ts,js,md,json}": "prettier --write"
}
}
}
2 changes: 1 addition & 1 deletion packages/client-documentation-generator/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
"@types/jest": "^26.0.4",
"@types/node": "^10.0.0",
"jest": "^26.1.0",
"typedoc": "^0.17.8",
"typedoc": "^0.19.2",
"typescript": "~4.0.2"
},
"homepage": "https://github.com/aws/aws-sdk-js-v3/tree/master/packages/client-documentation-generator",
Expand Down
5 changes: 5 additions & 0 deletions packages/client-documentation-generator/src/index.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
import { PluginHost } from "typedoc/dist/lib/utils";

import { SdkClientCommentUpdatePlugin } from "./sdk-client-comment-update";
import { SdkClientRemoveNavigatorPlugin } from "./sdk-client-remove-navigator";
import { SdkClientRenameProjectPlugin } from "./sdk-client-rename-project";
import { SdkClientTocPlugin } from "./sdk-client-toc-plugin";

Expand All @@ -17,4 +18,8 @@ module.exports = function load(pluginHost: PluginHost) {
"SdkClientRenameProjectPlugin",
new SdkClientRenameProjectPlugin(application.renderer)
);
application.renderer.addComponent(
"SdkClientRemoveNavigatorPlugin",
new SdkClientRemoveNavigatorPlugin(application.renderer)
);
};
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
import { Component, RendererComponent } from "typedoc/dist/lib/output/components";
import { RendererEvent } from "typedoc/dist/lib/output/events";
import { NavigationPlugin } from "typedoc/dist/lib/output/plugins";

@Component({ name: "SdkClientRemoveNavigator" })
export class SdkClientRemoveNavigatorPlugin extends RendererComponent {
private navigationPlugin: NavigationPlugin;

initialize() {
this.navigationPlugin = <any>this.owner.application.renderer.getComponent("navigation");
this.listenTo(this.owner, {
[RendererEvent.BEGIN]: this.onRenderedBegin,
});
}

onRenderedBegin(event: RendererEvent) {
const navigationItem = this.navigationPlugin.navigation;
if (!navigationItem) {
return;
}
navigationItem.children = [];
}
}
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
"@types/jest": "^26.0.4",
"@types/node": "^10.0.0",
"jest": "^26.1.0",
"typedoc": "^0.17.8",
"typedoc": "^0.19.2",
"typescript": "~4.0.2"
},
"private": true,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { isAbsolute, join, relative, resolve, sep } from "path";
import { BindOption } from "typedoc";
import { Component, RendererComponent } from "typedoc/dist/lib/output/components";
import { PageEvent } from "typedoc/dist/lib/output/events";
import { NavigationItem } from "typedoc/dist/lib/output/models/NavigationItem";

const PROJECT_ROOT = join(__dirname, "..", "..", "..", "..");
@Component({ name: "SdkIndexLinkClientPlugin" })
Expand All @@ -25,26 +26,69 @@ export class SdkIndexLinkClientPlugin extends RendererComponent {
onPageBegin(page: PageEvent) {
const out = isAbsolute(this.out) ? this.out : resolve(PROJECT_ROOT, this.out);
const clientDocs = isAbsolute(this.clientDocs) ? this.clientDocs : resolve(PROJECT_ROOT, this.clientDocs);

// Get relative path from core packages doc to clients' doc.
const clientDocsPattern = relative(out, clientDocs);

if (page.model === page.project) {
// Entry point index.html and global.html page.
page.project.children
.filter((child) => child.sources[0].fileName.startsWith(`clients${sep}`))
.forEach((child) => {
// "clients/client-s3" => "client-s3"
const clientName = child.sources[0].fileName.split(sep)[1];
const clientDocDir = clientDocsPattern.replace(/{{CLIENT}}/g, clientName);
child.url = join(clientDocDir, "index.html");
// @ts-ignore attach temporary flag.
child._skipRendering = true;
});
page.navigation = this.groupNavigation(page.navigation);

page.navigation.children.filter(this.isClient).forEach((child) => {
// "clients/client-s3" => "client-s3"
const clientName = child.reflection.sources[0].fileName.split(sep)[1];
const clientDocDir = clientDocsPattern.replace(/{{CLIENT}}/g, clientName);
child.url = join(clientDocDir, "index.html");
// @ts-ignore attach temporary flag.
child.reflection._skipRendering = true;
});
}

// Skip rendering empty landing page for each client.
if (page.model._skipRendering) {
page.preventDefault();
}
}

/**
* Group navigation in Client, Packages and Libraries sections. It will update the
* supplied navigation object;
*/
private groupNavigation(navigation: NavigationItem): NavigationItem {
if (this.isGrouped(navigation)) return navigation;

const modules = navigation.children.filter((child) => child?.reflection?.sources[0].fileName);
const clients: NavigationItem[] = [];
const packages: NavigationItem[] = [];
const libs: NavigationItem[] = [];
const isLib = (item: NavigationItem) => item?.reflection?.sources[0].fileName.startsWith(`lib${sep}`);
modules.forEach((item) => {
if (this.isClient(item)) {
clients.push(item);
} else if (isLib(item)) {
libs.push(item);
} else {
packages.push(item);
}
});

navigation.children = [
new NavigationItem("Clients"),
...clients,
new NavigationItem("Libraries"),
...libs,
new NavigationItem("Packages"),
...packages,
];
return navigation;
}

private isGrouped(navigation: NavigationItem): boolean {
const childrenNames = navigation.children.map((child) => child.title);
return (
childrenNames.includes("Clients") && childrenNames.includes("Packages") && childrenNames.includes("Libraries")
);
}

private isClient(item: NavigationItem): boolean {
return item?.reflection?.sources[0].fileName.startsWith(`clients${sep}`);
}
}
35 changes: 1 addition & 34 deletions yarn.lock
Original file line number Diff line number Diff line change
Expand Up @@ -5630,11 +5630,6 @@ [email protected]:
resolved "https://registry.yarnpkg.com/he/-/he-1.2.0.tgz#84ae65fa7eafb165fddb61566ae14baf05664f0f"
integrity sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==

highlight.js@^10.0.0:
version "10.3.1"
resolved "https://registry.yarnpkg.com/highlight.js/-/highlight.js-10.3.1.tgz#3ca6bf007377faae347e8135ff25900aac734b9a"
integrity sha512-jeW8rdPdhshYKObedYg5XGbpVgb1/DT4AHvDFXhkU7UnGSIjy9kkJ7zHG7qplhFHMitTSzh5/iClKQk3Kb2RFQ==

highlight.js@^10.2.0:
version "10.4.0"
resolved "https://registry.yarnpkg.com/highlight.js/-/highlight.js-10.4.0.tgz#ef3ce475e5dfa7a48484260b49ea242ddab823a0"
Expand Down Expand Up @@ -7624,7 +7619,7 @@ [email protected]:
dependencies:
lunr ">= 2.3.0 < 2.4.0"

"lunr@>= 2.3.0 < 2.4.0", lunr@^2.3.8:
"lunr@>= 2.3.0 < 2.4.0":
version "2.3.8"
resolved "https://registry.yarnpkg.com/lunr/-/lunr-2.3.8.tgz#a8b89c31f30b5a044b97d2d28e2da191b6ba2072"
integrity sha512-oxMeX/Y35PNFuZoHp+jUj5OSEmLCaIH4KTFJh7a93cHBoFmpw2IoPs22VIz7vyO2YUnx2Tn9dzIwO2P/4quIRg==
Expand Down Expand Up @@ -7717,11 +7712,6 @@ map-visit@^1.0.0:
dependencies:
object-visit "^1.0.0"

[email protected]:
version "1.0.0"
resolved "https://registry.yarnpkg.com/marked/-/marked-1.0.0.tgz#d35784245a04871e5988a491e28867362e941693"
integrity sha512-Wo+L1pWTVibfrSr+TTtMuiMfNzmZWiOPeO7rZsQUY5bgsxpHesBEcIWJloWVTFnrMXnf/TL30eTFSGJddmQAng==

[email protected]:
version "1.1.1"
resolved "https://registry.yarnpkg.com/marked/-/marked-1.1.1.tgz#e5d61b69842210d5df57b05856e0c91572703e6a"
Expand Down Expand Up @@ -11061,13 +11051,6 @@ typedarray@^0.0.6:
resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
integrity sha1-hnrHTjhkGHsdPUfZlqeOxciDB3c=

typedoc-default-themes@^0.10.2:
version "0.10.2"
resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.10.2.tgz#743380a80afe62c5ef92ca1bd4abe2ac596be4d2"
integrity sha512-zo09yRj+xwLFE3hyhJeVHWRSPuKEIAsFK5r2u47KL/HBKqpwdUSanoaz5L34IKiSATFrjG5ywmIu98hPVMfxZg==
dependencies:
lunr "^2.3.8"

typedoc-default-themes@^0.11.4:
version "0.11.4"
resolved "https://registry.yarnpkg.com/typedoc-default-themes/-/typedoc-default-themes-0.11.4.tgz#1bc55b7c8d1132844616ff6f570e1e2cd0eb7343"
Expand All @@ -11078,22 +11061,6 @@ typedoc-plugin-lerna-packages@^0.3.1:
resolved "https://registry.yarnpkg.com/typedoc-plugin-lerna-packages/-/typedoc-plugin-lerna-packages-0.3.1.tgz#3e65068e6c6ef987fc4c4553416af3fb22c8a5e6"
integrity sha512-azeP5DVv4Me+C32RoGbMAzXo7JeYmeEstMAx4mdtVGHLtrXjitlaf0pS562vogofwyIcyVnjL6BlZWvbPQ3hmw==

typedoc@^0.17.8:
version "0.17.8"
resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.17.8.tgz#96b67e9454aa7853bfc4dc9a55c8a07adfd5478e"
integrity sha512-/OyrHCJ8jtzu+QZ+771YaxQ9s4g5Z3XsQE3Ma7q+BL392xxBn4UMvvCdVnqKC2T/dz03/VXSLVKOP3lHmDdc/w==
dependencies:
fs-extra "^8.1.0"
handlebars "^4.7.6"
highlight.js "^10.0.0"
lodash "^4.17.15"
lunr "^2.3.8"
marked "1.0.0"
minimatch "^3.0.0"
progress "^2.0.3"
shelljs "^0.8.4"
typedoc-default-themes "^0.10.2"

typedoc@^0.19.2:
version "0.19.2"
resolved "https://registry.yarnpkg.com/typedoc/-/typedoc-0.19.2.tgz#842a63a581f4920f76b0346bb80eb2a49afc2c28"
Expand Down

0 comments on commit e6b2ae1

Please sign in to comment.