test(api-markdown-documenter): Add "deep" config end-to-end test cases (

#23586) Adds a test case that leverages new hierarchy options to create a "deep" suite configuration where documents that generate folder hierarchy yield documents named "index" _inside_ their folder,
microsoft · Jan 17, 2025 · 5f4097c · 5f4097c
1 parent 6c2cc1e
commit 5f4097c
Show file tree

Hide file tree

Showing 143 changed files with 4,502 additions and 71 deletions.
diff --git a/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts b/tools/api-markdown-documenter/src/test/EndToEndTestUtilities.ts
@@ -12,6 +12,7 @@ import { expect } from "chai";
 import { compare } from "dir-compare";
 
 import {
+	ApiItemUtilities,
 	FolderDocumentPlacement,
 	HierarchyKind,
 	type FolderHierarchyConfiguration,
@@ -99,55 +100,54 @@ export namespace HierarchyConfigurations {
 		[ApiItemKind.Variable]: HierarchyKind.Document,
 	};
 
-	// TODO
-	// const insideFolderOptions: FolderHierarchyConfiguration = {
-	// 	kind: HierarchyKind.Folder,
-	// 	documentPlacement: FolderDocumentPlacement.Inside,
-	// };
-	// /**
-	//  * "Deep" hierarchy: All "parent" API items generate hierarchy. All other items are rendered as documents under their parent hierarchy.
-	//  * @remarks Leads to many documents, but each document is likely to be relatively small.
-	//  */
-	// export const deep: HierarchyOptions = {
-	// 	// Items that introduce folder hierarchy:
-	// 	[ApiItemKind.Namespace]: insideFolderOptions,
-	// 	[ApiItemKind.Package]: insideFolderOptions,
-	// 	[ApiItemKind.Class]: insideFolderOptions,
-	// 	[ApiItemKind.Enum]: insideFolderOptions,
-	// 	[ApiItemKind.Interface]: insideFolderOptions,
-	// 	[ApiItemKind.TypeAlias]: insideFolderOptions,
-
-	// 	// Items that get their own document, but do not introduce folder hierarchy:
-	// 	[ApiItemKind.CallSignature]: HierarchyKind.Document,
-	// 	[ApiItemKind.Constructor]: HierarchyKind.Document,
-	// 	[ApiItemKind.ConstructSignature]: HierarchyKind.Document,
-	// 	[ApiItemKind.EnumMember]: HierarchyKind.Document,
-	// 	[ApiItemKind.Function]: HierarchyKind.Document,
-	// 	[ApiItemKind.IndexSignature]: HierarchyKind.Document,
-	// 	[ApiItemKind.Method]: HierarchyKind.Document,
-	// 	[ApiItemKind.MethodSignature]: HierarchyKind.Document,
-	// 	[ApiItemKind.Property]: HierarchyKind.Document,
-	// 	[ApiItemKind.PropertySignature]: HierarchyKind.Document,
-	// 	[ApiItemKind.Variable]: HierarchyKind.Document,
-
-	// 	getDocumentName: (apiItem, config): string => {
-	// 		switch (apiItem.kind) {
-	// 			case ApiItemKind.Model:
-	// 			case ApiItemKind.Package:
-	// 			case ApiItemKind.Namespace:
-	// 			case ApiItemKind.Class:
-	// 			case ApiItemKind.Enum:
-	// 			case ApiItemKind.Interface:
-	// 			case ApiItemKind.TypeAlias: {
-	// 				return "index";
-	// 			}
-	// 			default: {
-	// 				// Let the system generate a unique name that accounts for folder hierarchy.
-	// 				return ApiItemUtilities.createQualifiedDocumentNameForApiItem(apiItem, config);
-	// 			}
-	// 		}
-	// 	},
-	// };
+	const insideFolderOptions: FolderHierarchyConfiguration = {
+		kind: HierarchyKind.Folder,
+		documentPlacement: FolderDocumentPlacement.Inside,
+	};
+	/**
+	 * "Deep" hierarchy: All "parent" API items generate hierarchy. All other items are rendered as documents under their parent hierarchy.
+	 * @remarks Leads to many documents, but each document is likely to be relatively small.
+	 */
+	export const deep: HierarchyOptions = {
+		// Items that introduce folder hierarchy:
+		[ApiItemKind.Namespace]: insideFolderOptions,
+		[ApiItemKind.Package]: insideFolderOptions,
+		[ApiItemKind.Class]: insideFolderOptions,
+		[ApiItemKind.Enum]: insideFolderOptions,
+		[ApiItemKind.Interface]: insideFolderOptions,
+		[ApiItemKind.TypeAlias]: insideFolderOptions,
+
+		// Items that get their own document, but do not introduce folder hierarchy:
+		[ApiItemKind.CallSignature]: HierarchyKind.Document,
+		[ApiItemKind.Constructor]: HierarchyKind.Document,
+		[ApiItemKind.ConstructSignature]: HierarchyKind.Document,
+		[ApiItemKind.EnumMember]: HierarchyKind.Document,
+		[ApiItemKind.Function]: HierarchyKind.Document,
+		[ApiItemKind.IndexSignature]: HierarchyKind.Document,
+		[ApiItemKind.Method]: HierarchyKind.Document,
+		[ApiItemKind.MethodSignature]: HierarchyKind.Document,
+		[ApiItemKind.Property]: HierarchyKind.Document,
+		[ApiItemKind.PropertySignature]: HierarchyKind.Document,
+		[ApiItemKind.Variable]: HierarchyKind.Document,
+
+		getDocumentName: (apiItem, config): string => {
+			switch (apiItem.kind) {
+				case ApiItemKind.Model:
+				case ApiItemKind.Package:
+				case ApiItemKind.Namespace:
+				case ApiItemKind.Class:
+				case ApiItemKind.Enum:
+				case ApiItemKind.Interface:
+				case ApiItemKind.TypeAlias: {
+					return "index";
+				}
+				default: {
+					// Let the system generate a unique name that accounts for folder hierarchy.
+					return ApiItemUtilities.createQualifiedDocumentNameForApiItem(apiItem, config);
+				}
+			}
+		},
+	};
 }
 
 /**

diff --git a/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/HtmlEndToEnd.test.ts
@@ -67,17 +67,16 @@ const testConfigs = new Map<
 		},
 	],
 
-	// TODO
-	// // A sample "deep" configuration.
-	// // All "parent" API items generate hierarchy.
-	// // All other items are rendered as documents under their parent hierarchy.
-	// [
-	// 	"deep-config",
-	// 	{
-	// 		uriRoot: ".",
-	// 		hierarchy: HierarchyConfigurations.deep,
-	// 	},
-	// ],
+	// A sample "deep" configuration.
+	// All "parent" API items generate hierarchy.
+	// All other items are rendered as documents under their parent hierarchy.
+	[
+		"deep-config",
+		{
+			uriRoot: "",
+			hierarchy: HierarchyConfigurations.deep,
+		},
+	],
 ]);
 
 describe("HTML end-to-end tests", () => {

diff --git a/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts b/tools/api-markdown-documenter/src/test/MarkdownEndToEnd.test.ts
@@ -67,17 +67,16 @@ const testConfigs = new Map<
 		},
 	],
 
-	// TODO
-	// // A sample "deep" configuration.
-	// // All "parent" API items generate hierarchy.
-	// // All other items are rendered as documents under their parent hierarchy.
-	// [
-	// 	"deep-config",
-	// 	{
-	// 		uriRoot: ".",
-	// 		hierarchy: HierarchyConfigurations.deep,
-	// 	},
-	// ],
+	// A sample "deep" configuration.
+	// All "parent" API items generate hierarchy.
+	// All other items are rendered as documents under their parent hierarchy.
+	[
+		"deep-config",
+		{
+			uriRoot: "",
+			hierarchy: HierarchyConfigurations.deep,
+		},
+	],
 ]);
 
 describe("Markdown end-to-end tests", () => {

diff --git a/.../api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html b/.../api-markdown-documenter/src/test/snapshots/html/simple-suite-test/deep-config/index.html
@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+  </head>
+  <body>
+    <section>
+      <h1>API Overview</h1>
+      <section>
+        <h2>Packages</h2>
+        <table>
+          <thead>
+            <tr>
+              <th>Package</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td><a href="/test-suite-a/">test-suite-a</a></td>
+              <td>Test package</td>
+            </tr>
+            <tr>
+              <td><a href="/test-suite-b/">test-suite-b</a></td>
+              <td></td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+    </section>
+  </body>
+</html>