docs: Faker and utility pages (#1940)

1 files changed, 71 insertions, 38 deletions

diff --git a/scripts/apidoc/apiDocsWriter.ts b/scripts/apidoc/apiDocsWriter.ts
index 6f00f64a..ba1e4367 100644
--- a/scripts/apidoc/apiDocsWriter.ts
+++ b/scripts/apidoc/apiDocsWriter.ts
@@ -2,16 +2,17 @@ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { ProjectReflection } from 'typedoc';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
-import type { APIGroup, APIItem } from '../../docs/api/api-types';
+import type { APIGroup } from '../../docs/api/api-types';
 import { formatMarkdown, formatTypescript } from './format';
+import { extractSourceBaseUrl } from './typedoc';
+import type { DocsApiDiffIndex, ModuleSummary, Page } from './utils';
 import {
-  extractModuleName,
-  extractSourceBaseUrl,
-  selectApiMethods,
-  selectApiModules,
-} from './typedoc';
-import type { DocsApiDiffIndex, PageIndex } from './utils';
-import { pathDocsDiffIndexFile, pathDocsDir, pathOutputDir } from './utils';
+  diffHash,
+  methodDiffHash,
+  pathDocsDiffIndexFile,
+  pathDocsDir,
+  pathOutputDir,
+} from './utils';
 
 const pathDocsApiPages = resolve(pathDocsDir, '.vitepress', 'api-pages.ts');
 const pathDocsApiSearchIndex = resolve(
@@ -30,6 +31,52 @@ editLink: false
 `;
 
 /**
+ * Writes the api docs for the given modules.
+ *
+ * @param moduleName The name of the module to write the docs for.
+ * @param lowerModuleName The lowercase name of the module.
+ * @param comment The module comments.
+ * @param deprecated The deprecation message.
+ * @param methods The methods of the module.
+ */
+export function writeApiDocsModule(
+  moduleName: string,
+  lowerModuleName: string,
+  comment: string,
+  deprecated: string | undefined,
+  methods: Method[]
+): ModuleSummary {
+  writeApiDocsModulePage(
+    moduleName,
+    lowerModuleName,
+    comment,
+    deprecated,
+    methods
+  );
+  writeApiDocsModuleData(lowerModuleName, methods);
+
+  return {
+    text: moduleName,
+    link: `/api/${lowerModuleName}.html`,
+    methods,
+    diff: methods.reduce(
+      (data, method) => ({
+        ...data,
+        [method.name]: methodDiffHash(method),
+      }),
+      {
+        moduleHash: diffHash({
+          name: moduleName,
+          field: lowerModuleName,
+          deprecated,
+          comment,
+        }),
+      }
+    ),
+  };
+}
+
+/**
  * Writes the api page for the given module to the correct location.
  *
  * @param moduleName The name of the module to write the docs for.
@@ -37,7 +84,7 @@ editLink: false
  * @param comment The module comments.
  * @param methods The methods of the module.
  */
-export function writeApiDocsModulePage(
+function writeApiDocsModulePage(
   moduleName: string,
   lowerModuleName: string,
   comment: string,
@@ -94,7 +141,7 @@ export function writeApiDocsModulePage(
  * @param lowerModuleName The lowercase name of the module.
  * @param methods The methods data to save.
  */
-export function writeApiDocsData(
+function writeApiDocsModuleData(
   lowerModuleName: string,
   methods: Method[]
 ): void {
@@ -116,10 +163,9 @@ export function writeApiDocsData(
  *
  * @param pages The pages to write into the index.
  */
-export function writeApiPagesIndex(pages: PageIndex): void {
+export function writeApiPagesIndex(pages: Page[]): void {
   // Write api-pages.ts
   console.log('Updating api-pages.ts');
-  pages.sort((a, b) => a.text.localeCompare(b.text));
   pages.splice(0, 0, { text: 'Overview', link: '/api/' });
   let apiPagesContent = `
     // This file is automatically generated.
@@ -146,33 +192,20 @@ export function writeApiDiffIndex(diffIndex: DocsApiDiffIndex): void {
  *
  * @param project The typedoc project.
  */
-export function writeApiSearchIndex(project: ProjectReflection): void {
-  const apiIndex: APIGroup[] = [];
-
-  const moduleApiSection: APIGroup = {
-    text: 'Module API',
-    items: [],
-  };
-
-  apiIndex.push(moduleApiSection);
-
-  const apiModules = selectApiModules(project);
-
-  moduleApiSection.items = apiModules
-    .map((module) => {
-      const moduleName = extractModuleName(module);
-      const apiSection: APIItem = {
-        text: moduleName,
-        link: moduleName.toLowerCase(),
-        headers: selectApiMethods(module).map((child) => ({
-          anchor: child.name,
-          text: child.name,
+export function writeApiSearchIndex(pages: ModuleSummary[]): void {
+  const apiIndex: APIGroup[] = [
+    {
+      text: 'Module API',
+      items: pages.map((module) => ({
+        text: module.text,
+        link: module.link,
+        headers: module.methods.map((method) => ({
+          anchor: method.name,
+          text: method.name,
         })),
-      };
-
-      return apiSection;
-    })
-    .sort((a, b) => a.text.localeCompare(b.text));
+      })),
+    },
+  ];
 
   writeFileSync(pathDocsApiSearchIndex, JSON.stringify(apiIndex));
 }