@maci-protocol/website 0.0.0-ci.1e276ed

package/src/scripts/setupSolidityDocs.ts

@@ -0,0 +1,67 @@
+import fs from "fs";
+import path from "path";
+
+import { copyDirectory, generateToC, insertIndexPage } from "./utils";
+
+// where to move the solidity doc files over
+const solidityDocDir = path.resolve(
+  __dirname,
+  "../../versioned_docs/version-v3.x/technical-references/smart-contracts/solidity-docs",
+);
+// the origin folder (from the contracts package)
+const sourceDir = path.resolve(__dirname, "../../../../packages/contracts/docs");
+
+/**
+ * Currently, Solidity docgen generates the same heading for all files.
+ * We need to remove it and add the contract name as a heading.
+ * @param dir - the directory where the documentation files are located
+ */
+function updateHeadings(dir: string) {
+  const files = fs.readdirSync(dir);
+
+  files.forEach((file: string) => {
+    const absolutePath = path.join(dir, file);
+    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
+      let fileContent = fs.readFileSync(absolutePath, "utf8");
+
+      // Remove the "# Solidity API" line
+      fileContent = fileContent.replace("# Solidity API\n", "");
+
+      // Replace the first "##" with "#"
+      fileContent = fileContent.replace("##", "#");
+
+      // Escape {...} by wrapping them in backticks
+      fileContent = fileContent.replace(/{(.*?)}/g, "`{$1}`");
+
+      // Write the modified content back to the file
+      fs.writeFileSync(absolutePath, fileContent, "utf8");
+    }
+  });
+}
+
+// copy over the directory
+copyDirectory(sourceDir, solidityDocDir);
+// update the headings
+updateHeadings(solidityDocDir);
+// insert index page
+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.",
+);

package/src/scripts/setupTypedoc.ts

@@ -0,0 +1,112 @@
+import fs from "fs";
+import path from "path";
+
+import { copyDirectory, fitFormat, generateSidebarString, generateToC, insertIndexPage } from "./utils";
+
+const TYPEDOC_DIR = path.resolve(__dirname, "../../typedoc");
+
+/**
+ * A function that remove the auto-generated navigator
+ * and the title at the top of the page,
+ * meanwhile adding sidebar configurations above the content.
+ * @param file - the file being updated
+ * @param sidebarInfo - sidebar infos, passed in as a string
+ */
+function updateMdFiles(file: string, sidebarInfo: string) {
+  const content = fs.readFileSync(file).toString().split("\n");
+
+  if (content.length > 3) {
+    content.shift();
+    content.shift();
+    content.shift();
+  }
+
+  const writtenContent = content.join("\n").replaceAll("README.md", "index.md");
+  fs.writeFileSync(file, `${sidebarInfo}\n${writtenContent}`);
+}
+
+/**
+ * A function that parses a sub-directory of typedoc/,
+ * defines label for it and updates the markdown files.
+ * @param dir - the sub-directory being processed
+ */
+function parseAndRenameDirectory(dir: string) {
+  const dirname = path.resolve(TYPEDOC_DIR, dir);
+  const label = fitFormat(dir);
+
+  // only do things if it's a directory
+  if (fs.statSync(dirname).isDirectory()) {
+    const readmeFile = path.resolve(dirname, "README.md");
+
+    if (fs.existsSync(readmeFile)) {
+      updateMdFiles(readmeFile, generateSidebarString({ title: label, label }));
+      fs.renameSync(readmeFile, path.resolve(dirname, "index.md"));
+    }
+
+    // remove the first two lines of navigator
+    const modulesFile = path.resolve(dirname, "modules.md");
+
+    if (fs.existsSync(modulesFile)) {
+      updateMdFiles(modulesFile, generateSidebarString({ title: `${label} Module`, label: "module", position: 1 }));
+    }
+
+    processDirectory(dirname);
+  }
+}
+
+/**
+ * A function that processes a directory and updates the markdown files.
+ * @param directory - the directory being processed
+ */
+function processDirectory(directory: string) {
+  const items = fs.readdirSync(directory);
+  items.forEach((item) => {
+    const itemPath = path.resolve(directory, item);
+    if (fs.statSync(itemPath).isDirectory()) {
+      processDirectory(itemPath); // Recursively process subdirectories
+    } else if (fs.statSync(itemPath).isFile()) {
+      const itemLabel = item.split(".")[0];
+      updateMdFiles(itemPath, generateSidebarString({ title: itemLabel, label: itemLabel }));
+    }
+  });
+}
+
+/**
+ * A function that parses a sub-directory of typedoc/,
+ * defines label for it and updates the markdown files.
+ * @return target directory path for typedocs
+ */
+function defineTargetDirectory() {
+  const versionFile = path.resolve(__dirname, "../../versions.json");
+
+  if (fs.existsSync(versionFile)) {
+    const versionContent = fs.readFileSync(versionFile, "utf8");
+    if (versionContent) {
+      const versionContentJson = JSON.parse(versionContent) as string[];
+      return path.resolve(
+        __dirname,
+        `../../versioned_docs/version-${versionContentJson[0]}/technical-references/typescript-code/typedoc`,
+      );
+    }
+  }
+
+  return path.resolve(__dirname, "../../docs/technical-references/typescript-code/typedoc");
+}
+
+if (fs.existsSync(TYPEDOC_DIR)) {
+  const directories = fs.readdirSync(TYPEDOC_DIR, "utf8");
+  directories.forEach((dir) => {
+    parseAndRenameDirectory(dir);
+  });
+
+  insertIndexPage(
+    TYPEDOC_DIR,
+    { title: "Typedoc", label: "Typedoc" },
+    `\nTypedoc API documentation.\n${generateToC(TYPEDOC_DIR)}\n`,
+  );
+
+  const versionDir = defineTargetDirectory();
+  copyDirectory(TYPEDOC_DIR, versionDir);
+
+  fs.rmSync(TYPEDOC_DIR, { recursive: true, force: true });
+}

package/src/scripts/utils.ts

@@ -0,0 +1,115 @@
+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);
+    }
+  });
+}
+
+/**
+ * A function that forces the first letter to be capital,
+ * while the rest of the string must be lower case.
+ * @param str - the string being transformed
+ */
+export function fitFormat(str: string): string {
+  return `${str[0].toUpperCase()}${str.slice(1, str.length).toLowerCase()}`;
+}
+
+/**
+ * Sidebar Parameters
+ */
+interface SidebarProps {
+  title?: string;
+  description?: string;
+  label?: string;
+  position?: number;
+}
+
+/**
+ * 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 {
+  let ret = "---\n";
+
+  if (title) {
+    ret = `${ret}title: ${title}\n`;
+  }
+
+  if (description) {
+    ret = `${ret}description: ${description}\n`;
+  }
+
+  if (label) {
+    ret = `${ret}sidebar_label: ${label}\n`;
+  }
+
+  if (position) {
+    ret = `${ret}sidebar_position: ${position.toString()}\n`;
+  }
+
+  ret = `${ret}---\n`;
+
+  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,
+  content?: string,
+): void {
+  fs.writeFileSync(
+    `${dir}/index.md`,
+    `${generateSidebarString({ title, description, label, position })}${content ?? ""}`,
+  );
+}

package/src/utils/getProjectsByFilter.ts

@@ -0,0 +1,40 @@
+import type Projects from "../content/projects.json";
+
+/**
+ * Filters projects based on hackathon and status criteria.
+ * @param projects An array of objects where each object represents a project.
+ * @param filter An object containing optional hackathon and status filter criteria.
+ * @returns An array of projects that match the given filter criteria.
+ */
+export function getProjectsByFilter(
+  projects: typeof Projects,
+  filter: { hackathon?: string; status?: string },
+): typeof Projects {
+  return projects.filter((project) => {
+    const hackathonMatch = !filter.hackathon || project.hackathon === filter.hackathon;
+    const statusMatch = !filter.status || project.status === filter.status;
+    return hackathonMatch && statusMatch;
+  });
+}
+
+/**
+ * Extracts unique hackathons from the projects list.
+ * @param projects An array of objects where each object represents a project.
+ * @returns An array of strings, where each string is a unique hackathon from across all projects.
+ */
+export function getUniqueHackathons(projects: typeof Projects): string[] {
+  const hackathons = projects
+    .map((project) => project.hackathon)
+    .filter((hackathon): hackathon is string => hackathon !== null && hackathon !== "");
+  return Array.from(new Set(hackathons));
+}
+
+/**
+ * Extracts unique statuses from the projects list.
+ * @param projects An array of objects where each object represents a project.
+ * @returns An array of strings, where each string is a unique status from across all projects.
+ */
+export function getUniqueStatuses(projects: typeof Projects): string[] {
+  const statuses = projects.map((project) => project.status);
+  return Array.from(new Set(statuses));
+}