docs: make api reference landing prettier (#1727)

* feat(client-documentation-generator): skip too long navigation

* docs: update typedoc plugins dependencies

* docs(core-packages-documentation-generator): update landing page navigation

Author: AllanZhengYP

package.json

@@ -115,4 +115,4 @@
     ],
     "**/*.{ts,js,md,json}": "prettier --write"
   }
-}
+}

packages/client-documentation-generator/package.json

@@ -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",

packages/client-documentation-generator/src/index.ts

@@ -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";
 
@@ -17,4 +18,8 @@ module.exports = function load(pluginHost: PluginHost) {
     "SdkClientRenameProjectPlugin",
     new SdkClientRenameProjectPlugin(application.renderer)
   );
+  application.renderer.addComponent(
+    "SdkClientRemoveNavigatorPlugin",
+    new SdkClientRemoveNavigatorPlugin(application.renderer)
+  );
 };

packages/client-documentation-generator/src/sdk-client-remove-navigator.ts

@@ -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 = [];
+  }
+}

packages/core-packages-documentation-generator/package.json

@@ -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,

packages/core-packages-documentation-generator/src/sdk-index-link-client.ts

@@ -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" })
@@ -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}`);
+  }
 }

yarn.lock

@@ -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"
@@ -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==
@@ -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"
@@ -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"
@@ -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"