feat: build typedoc for website

package.json

@@ -6,7 +6,7 @@
   "license": "MIT",
   "scripts": {
     "bootstrap": "lerna bootstrap",
-    "build": "lerna run build",
+    "build": "lerna run build --ignore=website",
     "clean": "lerna exec -- rm -rf node_modules build && rm -rf node_modules",
     "commit": "git cz",
     "prettier": "prettier -c .",
@@ -18,7 +18,7 @@
     "test:cli": "lerna run test --scope \"maci-cli\"",
     "test:integration": "lerna run test --scope \"maci-integrationtests\"",
     "test": "lerna run test --ignore maci-integrationtests --ignore maci-cli",
-    "typedoc": "typedoc --options typedoc.json",
+    "typedoc": "typedoc --plugin typedoc-plugin-markdown --options typedoc.json",
     "prepare": "is-ci || husky install"
   },
   "author": "PSE",
@@ -48,6 +48,7 @@
     "prettier-plugin-solidity": "^1.2.0",
     "solhint": "^4.0.0",
     "typedoc": "^0.25.4",
+    "typedoc-plugin-markdown": "^3.17.1",
     "typescript": "^5.3.2"
   },
   "config": {

typedoc.json

@@ -11,5 +11,5 @@
     "./circuits/**/*",
     "./integrationTests/**/*"
   ],
-  "out": "./website/static/typedoc_output/"
+  "out": "./website/typedoc/"
 }

website/.gitignore

@@ -19,5 +19,5 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-static/typedoc_output
-versioned_docs/version-v1.x/solidity-docs
+versioned_docs/version-v1.x/solidity-docs
+versioned_docs/version-v1.x/typedoc

website/docusaurus.config.ts

@@ -96,11 +96,6 @@ const config: Config = {
           href: "/docs/introduction",
           position: "left",
         },
-        {
-          to: "/typedoc",
-          label: "TypeScript Docs",
-          position: "left",
-        },
         {
           to: "/blog",
           label: "Blog",

website/src/scripts/setupSolidityDocs.ts

@@ -1,39 +1,13 @@
 import fs from "fs";
 import path from "path";
 
+import { copyDirectory } from "./utils";
+
 // where to move the solidity doc files over
 const solidityDocDir = path.resolve(__dirname, "../../versioned_docs/version-v1.x/solidity-docs");
 // the origin folder (from the contracts package)
 const sourceDir = path.resolve(__dirname, "../../../contracts/docs");
 
-/**
- * Allow to copy a directory from source to target
- * @param source - the source directory
- * @param target - the target directory
- */
-function copyDirectory(source: string, target: string) {
-  if (!fs.existsSync(target)) {
-    fs.mkdirSync(target, { recursive: true });
-  }
-
-  if (!fs.existsSync(source)) {
-    return;
-  }
-
-  const files = fs.readdirSync(source);
-
-  files.forEach((file: string) => {
-    const sourcePath = path.join(source, file);
-    const targetPath = path.join(target, file);
-
-    if (fs.lstatSync(sourcePath).isDirectory()) {
-      copyDirectory(sourcePath, targetPath);
-    } else {
-      fs.copyFileSync(sourcePath, targetPath);
-    }
-  });
-}
-
 /**
  * Currently, Solidity docgen generates the same heading for all files.
  * We need to remove it and add the contract name as a heading.

website/src/scripts/setupTypedoc.ts

@@ -1,42 +1,56 @@
 import fs from "fs";
 import path from "path";
 
-// Define the directory where the Typedoc HTML files are located
-const typedocDir = path.resolve(__dirname, "../../static/typedoc_output");
+import { copyDirectory } from "./utils";
 
-// Define a recursive function to find all HTML files in a directory
-function findHtmlFiles(dir: string): string[] {
-  if (!fs.existsSync(dir)) {
-    return [];
-  }
+const TYPEDOC_DIR = path.resolve(__dirname, "../../typedoc");
+
+function updateMentionFiles(dirName: string) {
+  const dir = path.join(TYPEDOC_DIR, dirName);
   const files = fs.readdirSync(dir);
-  const list: string[] = [];
-
-  files.forEach((file: string) => {
-    if (fs.statSync(path.resolve(dir, file)).isDirectory()) {
-      list.concat(findHtmlFiles(path.resolve(dir, file)));
-    } else if (file.endsWith(".html")) {
-      list.push(path.resolve(dir, file));
-    }
+  files.forEach((file) => {
+    const filename = path.join(dir, file);
+    let content = fs.readFileSync(filename, "utf8");
+    content = content.replaceAll("../README.md", "../../introduction.md");
+    content = content.replaceAll("../modules.md", "../index.md");
+    fs.writeFileSync(filename, content);
   });
-
-  return list;
 }
 
-// Find all HTML files in the Typedoc directory
-const htmlFiles = findHtmlFiles(typedocDir);
+// Remove the README.md file if exists
+const readmeFile = path.join(TYPEDOC_DIR, "README.md");
+if (fs.existsSync(readmeFile)) {
+  fs.unlinkSync(readmeFile);
+}
 
-// Go through each HTML file and add the target="_parent" attribute to the external links
-htmlFiles.forEach((file: string) => {
-  let content = fs.readFileSync(file, "utf8");
+// Rename modules.md to index.md, and change the README.md mention to ../introduction.md
+const modulesFile = path.join(TYPEDOC_DIR, "modules.md");
+if (fs.existsSync(modulesFile)) {
+  let content = fs.readFileSync(modulesFile, "utf8");
+  content = content.replaceAll("README.md", "../introduction.md");
+  fs.writeFileSync(modulesFile, content);
+  fs.renameSync(modulesFile, path.join(TYPEDOC_DIR, "index.md"));
+}
 
-  // Add the target="_parent" attribute to the external links
-  content = content.replace(/<a href="http/g, '<a target="_parent" href="http');
+// Change all ../README.md mention to ../../introduction.md, and change all ../modeuls.md mention to ../index.md
+updateMentionFiles("classes");
+updateMentionFiles("interfaces");
+updateMentionFiles("modules");
+
+// find the target moving directory
+const versionFile = path.resolve(__dirname, "../../versions.json");
+let versionDir = "";
+try {
+  const versionContent = fs.readFileSync(versionFile, "utf8");
+  if (versionContent) {
+    const versionContentJson: string[] = JSON.parse(versionContent) as string[];
+    versionDir = path.resolve(__dirname, `../../versioned_docs/version-${versionContentJson[0]}/typedoc`);
+  }
+} catch (e) {
+  versionDir = path.resolve(__dirname, "../../docs/typedoc");
+}
 
-  content = content.replace(
-    /<a href="\.\//g,
-    '<a target="_parent" href="https://github.com/privacy-scaling-explorations/maci/tree/dev/',
-  );
+// move the typedoc/ directory to target directory
+copyDirectory(TYPEDOC_DIR, versionDir);
 
-  fs.writeFileSync(file, content);
-});
+fs.rmSync(TYPEDOC_DIR, { recursive: true, force: true });

website/src/scripts/utils.ts

@@ -0,0 +1,30 @@
+import fs from "fs";
+import path from "path";
+
+/**
+ * Allow to copy a directory from source to target
+ * @param source - the source directory
+ * @param target - the target directory
+ */
+export function copyDirectory(source: string, target: string): void {
+  if (!fs.existsSync(target)) {
+    fs.mkdirSync(target, { recursive: true });
+  }
+
+  if (!fs.existsSync(source)) {
+    return;
+  }
+
+  const files = fs.readdirSync(source);
+
+  files.forEach((file: string) => {
+    const sourcePath = path.join(source, file);
+    const targetPath = path.join(target, file);
+
+    if (fs.lstatSync(sourcePath).isDirectory()) {
+      copyDirectory(sourcePath, targetPath);
+    } else {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
+  });
+}

website/tsconfig.json

@@ -9,7 +9,7 @@
     "noUnusedParameters": true,
     "noImplicitReturns": true,
     "target": "ES2020",
-    "lib": ["es2020", "DOM"],
+    "lib": ["es2020", "DOM", "ES2021.String"],
     "experimentalDecorators": true,
     "strict": true,
     "noFallthroughCasesInSwitch": true,
@@ -30,5 +30,5 @@
     "sourceMap": true,
     "stripInternal": true
   },
-  "include": ["./src", "./docusaurus.config.ts", "./setupTypedoc.ts"]
+  "include": ["./src", "./docusaurus.config.ts"]
 }