RushStackFeature now generates a Jekyll navigation tree

Author: octogonz

Diff for: repo-scripts/doc-plugin-rush-stack/.vscode/launch.json

@@ -15,7 +15,7 @@
         "--input-folder",
         "../../common/temp/api",
         "--output-folder",
-        "./dist"
+        "./dist/api"
       ]
     },
   ]

Diff for: repo-scripts/doc-plugin-rush-stack/src/RushStackFeature.ts

@@ -1,14 +1,34 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { MarkdownDocumenterFeature, IMarkdownDocumenterFeatureOnBeforeWritePageArgs } from '@microsoft/api-documenter';
+import * as path from 'path';
+import yaml = require('js-yaml');
+import { FileSystem } from '@microsoft/node-core-library';
+import { ApiItem } from '@microsoft/api-extractor-model';
+import {
+  MarkdownDocumenterFeature,
+  IMarkdownDocumenterFeatureOnBeforeWritePageArgs,
+  IMarkdownDocumenterFeatureOnFinishedArgs
+} from '@microsoft/api-documenter';
+
+interface INavigationNode {
+  title: string;
+  url?: string;
+  subitems?: INavigationNode[];
+}
+interface INavigationFile {
+  api_nav: INavigationNode[];
+}
 
 export class RushStackFeature extends MarkdownDocumenterFeature {
+  private _apiItemsWithPages: Set<ApiItem> = new Set<ApiItem>();
+
   public onInitialized(): void {
     console.log('RushStackFeature: onInitialized()');
   }
 
   public onBeforeWritePage(eventArgs: IMarkdownDocumenterFeatureOnBeforeWritePageArgs): void {
+    // Add the Jekyll header
     const header: string = [
       '---',
       'layout: page',
@@ -18,5 +38,39 @@ export class RushStackFeature extends MarkdownDocumenterFeature {
       ''
     ].join('\n');
     eventArgs.pageContent = header + eventArgs.pageContent;
+
+    this._apiItemsWithPages.add(eventArgs.apiItem);
+  }
+
+  public onFinished(eventArgs: IMarkdownDocumenterFeatureOnFinishedArgs): void {
+    const navigationFile: INavigationFile = {
+      api_nav: []
+    };
+    this._buildNavigation(navigationFile.api_nav, this.context.apiModel);
+
+    const navFilePath: string = path.join(this.context.outputFolder, '..', 'api_nav.yaml');
+    const navFileContent: string = yaml.safeDump(navigationFile, { lineWidth: 120 });
+
+    FileSystem.writeFile(navFilePath, navFileContent, { ensureFolderExists: true });
+  }
+
+  private _buildNavigation(parentNodes: INavigationNode[], parentApiItem: ApiItem): void {
+    for (const apiItem of parentApiItem.members) {
+      if (this._apiItemsWithPages.has(apiItem)) {
+        const newNode: INavigationNode = {
+          title: apiItem.displayName,
+          url: path.posix.join('/pages/api/', this.context.documenter.getLinkForApiItem(apiItem)!).replace(/\.md$/, '')
+        };
+        parentNodes.push(newNode);
+
+        const newNodeSubitems: INavigationNode[] = [];
+        this._buildNavigation(newNodeSubitems, apiItem);
+        if (newNodeSubitems.length > 0) {
+          newNode.subitems = newNodeSubitems;
+        }
+      } else {
+        this._buildNavigation(parentNodes, apiItem);
+      }
+    }
   }
 }

Diff for: repo-scripts/generate-api-docs/generate-api-docs.cmd

@@ -1,2 +1,2 @@
 @echo off
-.\node_modules\.bin\api-documenter generate --input-folder ..\..\common\temp\api --output-folder .\dist
+.\node_modules\.bin\api-documenter generate --input-folder ..\..\common\temp\api --output-folder .\dist\api