docs: restructure apidocs page tree (#2530)

Co-authored-by: larvide <[email protected]>

7 files changed, 61 insertions, 36 deletions

diff --git a/docs/.vitepress/api-pages.ts b/docs/.vitepress/api-pages.ts
index dad86954..c23e6cfc 100644
--- a/docs/.vitepress/api-pages.ts
+++ b/docs/.vitepress/api-pages.ts
@@ -4,32 +4,37 @@ export const apiPages = [
   { text: 'Overview', link: '/api/' },
   { text: 'Faker', link: '/api/faker.html' },
   { text: 'SimpleFaker', link: '/api/simpleFaker.html' },
-  { text: 'Airline', link: '/api/airline.html' },
-  { text: 'Animal', link: '/api/animal.html' },
-  { text: 'Color', link: '/api/color.html' },
-  { text: 'Commerce', link: '/api/commerce.html' },
-  { text: 'Company', link: '/api/company.html' },
-  { text: 'Database', link: '/api/database.html' },
-  { text: 'Datatype', link: '/api/datatype.html' },
-  { text: 'Date', link: '/api/date.html' },
-  { text: 'Finance', link: '/api/finance.html' },
-  { text: 'Git', link: '/api/git.html' },
-  { text: 'Hacker', link: '/api/hacker.html' },
-  { text: 'Helpers', link: '/api/helpers.html' },
-  { text: 'Image', link: '/api/image.html' },
-  { text: 'Internet', link: '/api/internet.html' },
-  { text: 'Location', link: '/api/location.html' },
-  { text: 'Lorem', link: '/api/lorem.html' },
-  { text: 'Music', link: '/api/music.html' },
-  { text: 'Number', link: '/api/number.html' },
-  { text: 'Person', link: '/api/person.html' },
-  { text: 'Phone', link: '/api/phone.html' },
-  { text: 'Random', link: '/api/random.html' },
-  { text: 'Science', link: '/api/science.html' },
-  { text: 'String', link: '/api/string.html' },
-  { text: 'System', link: '/api/system.html' },
-  { text: 'Vehicle', link: '/api/vehicle.html' },
-  { text: 'Word', link: '/api/word.html' },
   { text: 'Randomizer', link: '/api/randomizer.html' },
   { text: 'Utilities', link: '/api/utils.html' },
+  {
+    text: 'Modules',
+    items: [
+      { text: 'Airline', link: '/api/airline.html' },
+      { text: 'Animal', link: '/api/animal.html' },
+      { text: 'Color', link: '/api/color.html' },
+      { text: 'Commerce', link: '/api/commerce.html' },
+      { text: 'Company', link: '/api/company.html' },
+      { text: 'Database', link: '/api/database.html' },
+      { text: 'Datatype', link: '/api/datatype.html' },
+      { text: 'Date', link: '/api/date.html' },
+      { text: 'Finance', link: '/api/finance.html' },
+      { text: 'Git', link: '/api/git.html' },
+      { text: 'Hacker', link: '/api/hacker.html' },
+      { text: 'Helpers', link: '/api/helpers.html' },
+      { text: 'Image', link: '/api/image.html' },
+      { text: 'Internet', link: '/api/internet.html' },
+      { text: 'Location', link: '/api/location.html' },
+      { text: 'Lorem', link: '/api/lorem.html' },
+      { text: 'Music', link: '/api/music.html' },
+      { text: 'Number', link: '/api/number.html' },
+      { text: 'Person', link: '/api/person.html' },
+      { text: 'Phone', link: '/api/phone.html' },
+      { text: 'Random', link: '/api/random.html' },
+      { text: 'Science', link: '/api/science.html' },
+      { text: 'String', link: '/api/string.html' },
+      { text: 'System', link: '/api/system.html' },
+      { text: 'Vehicle', link: '/api/vehicle.html' },
+      { text: 'Word', link: '/api/word.html' },
+    ],
+  },
 ];
diff --git a/scripts/apidoc/faker-class.ts b/scripts/apidoc/faker-class.ts
index 44648831..6672896c 100644
--- a/scripts/apidoc/faker-class.ts
+++ b/scripts/apidoc/faker-class.ts
@@ -55,7 +55,8 @@ async function processClass(
     comment,
     examples,
     deprecated,
-    methods
+    methods,
+    ''
   );
 }
 
diff --git a/scripts/apidoc/faker-utilities.ts b/scripts/apidoc/faker-utilities.ts
index 0da03581..ad1f74c3 100644
--- a/scripts/apidoc/faker-utilities.ts
+++ b/scripts/apidoc/faker-utilities.ts
@@ -34,6 +34,7 @@ async function processUtilities(
     comment,
     undefined,
     undefined,
-    methods
+    methods,
+    ''
   );
 }
diff --git a/scripts/apidoc/generate.ts b/scripts/apidoc/generate.ts
index 316757cc..44610869 100644
--- a/scripts/apidoc/generate.ts
+++ b/scripts/apidoc/generate.ts
@@ -24,13 +24,15 @@ export async function generate(): Promise<void> {
 
   const pages = [
     ...(await processFakerClasses(project)),
+    await processFakerRandomizer(project),
+    await processFakerUtilities(project),
     ...(await processModules(project)).sort((a, b) =>
       a.text.localeCompare(b.text)
     ),
-    await processFakerRandomizer(project),
-    await processFakerUtilities(project),
   ];
-  await writeApiPagesIndex(pages.map(({ text, link }) => ({ text, link })));
+  await writeApiPagesIndex(
+    pages.map(({ text, link, category }) => ({ text, link, category }))
+  );
   writeApiDiffIndex(
     Object.fromEntries(pages.map(({ text, diff }) => [text, diff]))
   );
diff --git a/scripts/apidoc/module-methods.ts b/scripts/apidoc/module-methods.ts
index 772a7236..c21ccf97 100644
--- a/scripts/apidoc/module-methods.ts
+++ b/scripts/apidoc/module-methods.ts
@@ -57,7 +57,8 @@ async function processModule(
     comment,
     examples,
     deprecated,
-    methods
+    methods,
+    'Modules'
   );
 }
 
diff --git a/scripts/apidoc/utils.ts b/scripts/apidoc/utils.ts
index b6b533f6..18176da5 100644
--- a/scripts/apidoc/utils.ts
+++ b/scripts/apidoc/utils.ts
@@ -4,7 +4,7 @@ import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 
 // Types
 
-export type Page = { text: string; link: string };
+export type Page = { text: string; link: string; category: string };
 
 export type ModuleSummary = Page & {
   methods: Method[];
diff --git a/scripts/apidoc/writer.ts b/scripts/apidoc/writer.ts
index 0fc7ae78..23586230 100644
--- a/scripts/apidoc/writer.ts
+++ b/scripts/apidoc/writer.ts
@@ -2,8 +2,10 @@ import { writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import type { ProjectReflection } from 'typedoc';
 import { ReflectionKind } from 'typedoc';
+import type { DefaultTheme } from 'vitepress';
 import type { Method } from '../../docs/.vitepress/components/api-docs/method';
 import type { APIGroup } from '../../docs/api/api-types';
+import { groupBy } from '../../src/internal/group-by';
 import { formatMarkdown, formatTypescript } from './format';
 import { extractSourceBaseUrl } from './typedoc';
 import type { DocsApiDiffIndex, ModuleSummary, Page } from './utils';
@@ -40,6 +42,7 @@ editLink: false
  * @param examples The example code.
  * @param deprecated The deprecation message.
  * @param methods The methods of the module.
+ * @param category The category of the module.
  */
 export async function writeApiDocsModule(
   moduleName: string,
@@ -47,7 +50,8 @@ export async function writeApiDocsModule(
   comment: string,
   examples: string | undefined,
   deprecated: string | undefined,
-  methods: Method[]
+  methods: Method[],
+  category: string
 ): Promise<ModuleSummary> {
   await writeApiDocsModulePage(
     moduleName,
@@ -63,6 +67,7 @@ export async function writeApiDocsModule(
     text: moduleName,
     link: `/api/${lowerModuleName}.html`,
     methods,
+    category,
     diff: {
       moduleHash: diffHash({
         name: moduleName,
@@ -164,13 +169,23 @@ function writeApiDocsModuleData(
  * @param pages The pages to write into the index.
  */
 export async function writeApiPagesIndex(pages: Page[]): Promise<void> {
+  const pagesByCategory = groupBy(pages, (page) => page.category);
+  const pageTree = Object.entries(pagesByCategory).flatMap(
+    ([category, items]): DefaultTheme.SidebarItem[] => {
+      const cleanedItems = items.map(({ text, link }) => ({ text, link }));
+      return category
+        ? [{ text: category, items: cleanedItems }]
+        : cleanedItems;
+    }
+  );
+
   // Write api-pages.ts
   console.log('Updating api-pages.ts');
-  pages.splice(0, 0, { text: 'Overview', link: '/api/' });
+  pageTree.splice(0, 0, { text: 'Overview', link: '/api/' });
   let apiPagesContent = `
     // This file is automatically generated.
     // Run '${scriptCommand}' to update
-    export const apiPages = ${JSON.stringify(pages)};
+    export const apiPages = ${JSON.stringify(pageTree)};
     `.replace(/\n +/, '\n');
 
   apiPagesContent = await formatTypescript(apiPagesContent);