feat: restructure typedoc directories to support the docs hub (#1155)

* feat: alter typedoc postbuild script to restructure typedoc directories

* feat: generate api links for vitepress config

* feat: install replace

* feat: alter postbuild docs script to auto build links and alter file structure

* chore: empty changeset

* feat: fix typedoc postbuild sidebar generator

* feat: fix hardcoded regexes in typedoc postbuild

* chore: lint fix

---------

Co-authored-by: danielbate <--global>

.changeset/lovely-chicken-flash.md

@@ -0,0 +1,2 @@
+---
+---

apps/docs/.gitignore

@@ -1,4 +1,6 @@
 .vitepress/cache
 .vitepress/.temp
 
+.typedoc/api-links.json
+
 src/api

apps/docs/.vitepress/config.ts

@@ -1,6 +1,7 @@
 import { defineConfig } from 'vitepress';
 import { codeInContextPlugin } from './plugins/codeInContextPlugin';
 import { snippetPlugin } from './plugins/snippetPlugin';
+import apiLinks from '../.typedoc/api-links.json';
 
 export default defineConfig({
   title: 'Fuels-ts',
@@ -358,42 +359,7 @@ export default defineConfig({
           },
         ],
       },
-      {
-        text: 'API',
-        link: '/api/',
-        items: [
-          {
-            text: 'Address',
-            link: '/api/modules/fuel_ts_address',
-            collapsed: true,
-            items: [
-              {
-                text: 'Address',
-                link: '/api/classes/fuel_ts_address-Address',
-              },
-            ],
-          },
-          {
-            text: 'Interfaces',
-            link: '/api/modules/fuel_ts_interfaces',
-            collapsed: true,
-            items: [
-              {
-                text: 'AbstractAccount',
-                link: 'api/classes/fuel_ts_interfaces-AbstractAccount',
-              },
-              {
-                text: 'AbstractAddress',
-                link: 'api/classes/fuel_ts_interfaces-AbstractAddress',
-              },
-              {
-                text: 'AbstractContract',
-                link: 'api/classes/fuel_ts_interfaces-AbstractContract',
-              },
-            ],
-          },
-        ],
-      },
+      apiLinks,
     ],
   },
 });

apps/docs/package.json

@@ -4,10 +4,10 @@
   "version": "0.41.6",
   "description": "",
   "scripts": {
-    "dev": "nodemon --config nodemon.config.json -x 'typedoc && vitepress dev'",
-    "build": "typedoc && tsx ./scripts/typedoc-postbuild.ts && vitepress build",
-    "preview": "typedoc && vitepress preview",
-    "docs": "typedoc"
+    "dev": "nodemon --config nodemon.config.json -x 'pnpm run docs && vitepress dev'",
+    "build": "pnpm run docs && vitepress build",
+    "preview": "pnpm run docs && vitepress preview",
+    "docs": "typedoc && tsx ./scripts/typedoc-postbuild.ts"
   },
   "keywords": [],
   "author": "",
@@ -22,6 +22,7 @@
     "flexsearch": "^0.7.31",
     "markdown-it": "^13.0.1",
     "nodemon": "^2.0.22",
+    "replace": "^1.2.2",
     "typedoc": "^0.24.8",
     "typedoc-plugin-merge-modules": "^5.0.1",
     "vitepress": "1.0.0-alpha.51",

apps/docs/scripts/typedoc-postbuild.ts

@@ -1,17 +1,139 @@
-import { unlink } from 'fs';
+import { readdirSync, mkdirSync, copyFileSync, rmSync, renameSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import replace from 'replace';
+
+type Link = {
+  link: string;
+  text: string;
+  items: Link[];
+  collapsed?: boolean;
+};
 
 /**
- * Post build script to trim off undesired leftovers from Typedoc.
+ * Post build script to trim off undesired leftovers from Typedoc, restructure directories and generate json for links.
  */
 const docsDir = join(__dirname, '../src/');
-const filesToRemove = ['api/modules.md'];
+const apiDocsDir = join(docsDir, '/api');
+const classesDir = join(apiDocsDir, '/classes');
+const modulesDir = join(apiDocsDir, '/modules');
+
+const filesToRemove = ['modules.md', 'api/modules.md', 'api/classes', 'api/modules'];
+
 const { log } = console;
 
-filesToRemove.forEach((filePath) => {
-  const fullFilePath = join(docsDir, filePath);
-  unlink(fullFilePath, (err) => {
-    if (err) throw err;
-    log(`Removed ${fullFilePath}`);
+/**
+ * Removes unwanted files and dirs generated by typedoc.
+ */
+const removeUnwantedFiles = () => {
+  filesToRemove.forEach((dirPath) => {
+    const fullDirPath = join(docsDir, dirPath);
+    rmSync(fullDirPath, { recursive: true, force: true });
+  });
+};
+
+/**
+ * Generates a json file containing the links for the sidebar to be used by vitepress.
+ */
+const exportLinksJson = () => {
+  const links: Link = { link: '/api/', text: 'API', items: [] };
+  const directories = readdirSync(apiDocsDir);
+  directories
+    .filter((directory) => directory !== 'index.md')
+    .forEach((directory) => {
+      links.items.push({ text: directory, link: `/api/${directory}/`, collapsed: true, items: [] });
+      readdirSync(join(apiDocsDir, directory))
+        .filter((file) => file !== 'index.md')
+        .forEach((file) => {
+          const index = links.items.findIndex((item) => item.text === directory);
+          if (index !== -1) {
+            const name = file.split('.')[0];
+            links.items[index].items.push({
+              text: name,
+              link: `/api/${directory}/${name}`,
+              items: [],
+            });
+          }
+        });
+    });
+
+  writeFileSync('.typedoc/api-links.json', JSON.stringify(links));
+};
+
+/**
+ * Alters the typedoc generated file structure to be more semantic.
+ */
+const alterFileStructure = () => {
+  const modulesFiles = readdirSync(modulesDir);
+  const classesFiles = readdirSync(classesDir);
+
+  modulesFiles.forEach((modulesFile) => {
+    // Create a new directory for each module
+    const newDirName = modulesFile.split('.')[0];
+    const newDirPath = join(apiDocsDir, newDirName);
+    mkdirSync(newDirPath);
+
+    // Copy the class files to the correct module directory
+    classesFiles.forEach((classesFile) => {
+      if (classesFile.startsWith(newDirName)) {
+        const newDirClassFilePath = join(newDirPath, classesFile);
+        copyFileSync(join(classesDir, classesFile), newDirClassFilePath);
+
+        // Rename the class file to remove module prefix
+        renameSync(newDirClassFilePath, join(newDirPath, classesFile.split('-')[1]));
+      }
+    });
+
+    // Move module index file
+    copyFileSync(join(modulesDir, modulesFile), join(newDirPath, 'index.md'));
+
+    // Rename module directory to remove 'fuel_ts_' prefix
+    const formattedDirName = newDirPath.split('fuel_ts_')[1];
+    const capitalisedDirName = formattedDirName.charAt(0).toUpperCase() + formattedDirName.slice(1);
+    renameSync(newDirPath, join(apiDocsDir, capitalisedDirName));
   });
-});
+};
+
+/**
+ * Recreates the generated typedoc links
+ *
+ * TODO: this should be done via the filesystem rather than hardcoded
+ */
+const recreateInternalLinks = () => {
+  const regexReplaces = [
+    // Module replacements
+    { regex: 'fuel_ts_address.md', replacement: '/api/Address/index.md' },
+    { regex: 'fuel_ts_interfaces.md', replacement: '/api/Interfaces/index.md' },
+    // Class replacements
+    { regex: 'address-Address.md', replacement: '/api/Address/Address.md' },
+    { regex: 'interfaces-AbstractAccount.md', replacement: '/api/Interfaces/AbstractAccount.md' },
+    { regex: 'interfaces-AbstractAddress.md', replacement: '/api/Interfaces/AbstractAddress.md' },
+    { regex: 'interfaces-AbstractContract.md', replacement: '/api/Interfaces/AbstractContract.md' },
+    // Prefix cleanups
+    { regex: '../modules/', replacement: '/api/' },
+    { regex: '../classes/', replacement: '/api/' },
+    { regex: 'fuel_ts_', replacement: '' },
+    { regex: '/api//api/', replacement: '/api/' },
+  ];
+
+  const topLevelDirs = readdirSync(apiDocsDir);
+
+  topLevelDirs
+    .filter((dir) => dir !== 'index.md')
+    .forEach((dir) => {
+      regexReplaces.forEach(({ regex, replacement }) => {
+        replace({
+          regex,
+          replacement,
+          paths: [join(apiDocsDir, dir)],
+          recursive: true,
+          silent: true,
+        });
+      });
+    });
+};
+
+log('Cleaning up docs.');
+alterFileStructure();
+removeUnwantedFiles();
+exportLinksJson();
+recreateInternalLinks();