Merge pull request #1478 from privacy-scaling-explorations/docs/index…

…-page-autogenerated

docs(solidity-docs): add index page inside folders

website/src/scripts/setupSolidityDocs.ts

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 
-import { copyDirectory, insertIndexPage } from "./utils";
+import { copyDirectory, generateToC, insertIndexPage } from "./utils";
 
 // where to move the solidity doc files over
 const solidityDocDir = path.resolve(
@@ -24,6 +24,14 @@ function updateHeadings(dir: string) {
     const isDirectory = fs.statSync(absolutePath).isDirectory();
 
     if (isDirectory) {
+      insertIndexPage(
+        absolutePath,
+        { title: file, label: file },
+        `
+          Documentation for smart contracts inside the ${file} folder.\n
+          ${generateToC(absolutePath)}\n
+        `,
+      );
       updateHeadings(absolutePath);
     } else {
       // Read the content of the file
@@ -49,4 +57,11 @@ copyDirectory(sourceDir, solidityDocDir);
 // update the headings
 updateHeadings(solidityDocDir);
 // insert index page
-insertIndexPage(solidityDocDir, { title: "Solidity Docs", label: "Solidity Docs" });
+insertIndexPage(
+  solidityDocDir,
+  {
+    title: "Solidity Docs",
+    label: "Solidity Docs",
+  },
+  "This is a collection of the Solidity documentation for the MACI protocol. It is autogenerated with solidity-docs and should serve as a good starting point for understanding the codebase.",
+);

website/src/scripts/setupTypedoc.ts

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 
-import { copyDirectory, fitFormat, generateSidebarString, insertIndexPage } from "./utils";
+import { copyDirectory, fitFormat, generateSidebarString, generateToC, insertIndexPage } from "./utils";
 
 const TYPEDOC_DIR = path.resolve(__dirname, "../../typedoc");
 
@@ -96,7 +96,11 @@ if (fs.existsSync(TYPEDOC_DIR)) {
     parseAndRenameDirectory(dir);
   });
 
-  insertIndexPage(TYPEDOC_DIR, { title: "Typedoc", label: "Typedoc" });
+  insertIndexPage(
+    TYPEDOC_DIR,
+    { title: "Typedoc", label: "Typedoc" },
+    `\nTypedoc API documentation.\n${generateToC(TYPEDOC_DIR)}\n`,
+  );
 
   const versionDir = defineTargetDirectory();
   copyDirectory(TYPEDOC_DIR, versionDir);

website/src/scripts/utils.ts

@@ -49,8 +49,7 @@ interface SidebarProps {
 }
 
 /**
- * A function that forces the first letter to be capital,
- * while the rest of the string must be lower case.
+ * A function to generate a sidebar string for a markdown file
  * @param sidebarProps - including title, description, label, and position
  */
 export function generateSidebarString({ title, description, label, position }: SidebarProps): string {
@@ -77,11 +76,40 @@ export function generateSidebarString({ title, description, label, position }: S
   return ret;
 }
 
+/**
+ * Generate a table of contents for a directory
+ * @param dir - the directory to generate a table of contents for
+ * @returns a string with the table of contents
+ */
+export function generateToC(dir: string, prefix = ""): string {
+  const files = fs.readdirSync(dir);
+  let content = "";
+
+  files.forEach((file) => {
+    const filePath = path.join(dir, file);
+    const fileStat = fs.statSync(filePath);
+    if (fileStat.isDirectory()) {
+      content += generateToC(filePath, `${prefix}${file}/`);
+    } else if (file !== "index.md" && file !== "README.md" && file.endsWith(".md")) {
+      content += `- [${prefix}${file}](${prefix}${file})\n`;
+    }
+  });
+
+  return content;
+}
+
 /**
  * A function that insert a index page
  * @param dir - the directory to insert an index page
  * @param sidebarProps - including title, description, label, and position
  */
-export function insertIndexPage(dir: string, { title, description, label, position }: SidebarProps): void {
-  fs.writeFileSync(`${dir}/index.md`, generateSidebarString({ title, description, label, position }));
+export function insertIndexPage(
+  dir: string,
+  { title, description, label, position }: SidebarProps,
+  content?: string,
+): void {
+  fs.writeFileSync(
+    `${dir}/index.md`,
+    `${generateSidebarString({ title, description, label, position })}${content ?? ""}`,
+  );
 }

website/versioned_docs/version-v2.0_alpha/contributing/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Contributing",
-  "position": 10,
+  "position": 9,
   "link": {
     "type": "generated-index",
     "description": "MACI's contribution guidelines."

website/versioned_docs/version-v2.0_alpha/processes/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Processes",
-  "position": 8,
+  "position": 10,
   "link": {
     "type": "generated-index",
     "description": "Understand releasing and MACI's CI/CD pipeline."

website/versioned_docs/version-v2.0_alpha/project-ideas/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Project Ideas",
-  "position": 9,
+  "position": 8,
   "link": {
     "type": "generated-index",
     "description": "Get inspired on what to build on MACI."