feat: add action gen docs

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+
+jobs:
+  deploy-docs:
+    # Remove the following line if you wish to deploy the documentation to Vercel
+    if: false
+    name: Deploy docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+
+      - name: Install node
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.x
+          cache: 'yarn'
+
+      - name: Install dependencies
+        run: yarn --frozen-lockfile --network-concurrency 1
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: nightly
+
+      - name: Build Docs
+        run: yarn docs:build
+
+      - name: Create book folder
+        run: mdbook build docs
+
+      - uses: amondnet/vercel-action@v25
+        with:
+          vercel-token: ${{ secrets.VERCEL_TOKEN }}
+          vercel-org-id: ${{ secrets.ORG_ID}}
+          scope: ${{ secrets.ORG_ID}}
+          vercel-args: ${{ github.ref_name == 'main' && '--prod' || '' }}
+          vercel-project-id: ${{ secrets.PROJECT_ID}}
+          working-directory: ./docs/book

build-docs.js

@@ -0,0 +1,99 @@
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const tempFolder = 'technical-docs';
+const baseFolder = `docs`;
+
+const basePath = `${baseFolder}/src`;
+const tempPath = `${tempFolder}/src`;
+
+// Function to generate docs in a temporary directory
+const generateDocs = () => {
+  execSync(`FOUNDRY_PROFILE=docs forge doc --out "${tempFolder}"`);
+};
+
+// Function to edit generated summary not to have container pages
+const editSummaryContainerPages = () => {
+  // TODO: Implement this part to edit generated summary
+};
+
+// Function to edit generated summary titles to start with an uppercase letter
+const editSummaryTitles = () => {
+  // TODO: Implement this part to edit generated summary titles
+};
+
+// Function to edit the SUMMARY after the Interfaces section
+const editSummaryAfterInterfaces = () => {
+  const osType = process.platform;
+  const summaryFilePath = `${basePath}/SUMMARY.md`;
+  const tempSummaryFilePath = `${tempPath}/SUMMARY.md`;
+
+  const interfacesSectionEndPattern = '\\Technical Documentation';
+
+  mkdir(`${basePath}`);
+  execSync(`touch ${summaryFilePath}`);
+
+  const sedCommand = osType.startsWith('darwin')
+    ? `sed -i '' -e '/${interfacesSectionEndPattern}/q' ${summaryFilePath}`
+    : `sed -i -e '/${interfacesSectionEndPattern}/q' ${summaryFilePath}`;
+
+  execSync(sedCommand);
+
+  const summaryContent = fs.readFileSync(tempSummaryFilePath, 'utf8');
+  const updatedContent = fs.readFileSync(tempSummaryFilePath, 'utf8').split('\n').slice(4).join('\n');
+  const editedSummaryContent =
+    fs.readFileSync(summaryFilePath, 'utf8').split(interfacesSectionEndPattern)[0] + updatedContent;
+  fs.writeFileSync(summaryFilePath, editedSummaryContent);
+};
+
+// Function to delete old generated interfaces docs
+const deleteOldGeneratedDocs = () => {
+  fs.rmSync(`${basePath}`, { recursive: true });
+};
+
+// Function to move new generated interfaces docs from tmp to original directory
+const moveNewGeneratedDocs = () => {
+  mkdir(`${basePath}`);
+  fs.cpSync(`${tempPath}`, `${basePath}`, { recursive: true });
+};
+
+// Function to delete tmp directory
+const deleteTempDirectory = () => {
+  fs.rmSync(tempFolder, { recursive: true });
+};
+
+// Function to replace text in all files (to fix the internal paths)
+const replaceText = (dir) => {
+  fs.readdirSync(dir).forEach((file) => {
+    const filePath = path.join(dir, file);
+    if (fs.statSync(filePath).isFile()) {
+      let content = fs.readFileSync(filePath, 'utf8');
+      content = content.replace(new RegExp(`${tempPath}/`, 'g'), '');
+      fs.writeFileSync(filePath, content);
+    } else if (fs.statSync(filePath).isDirectory()) {
+      replaceText(filePath);
+    }
+  });
+};
+
+// Function to create directory if it does not exist
+const mkdir = (dir) => {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+};
+
+// Main function to execute all tasks
+const main = () => {
+  generateDocs();
+  editSummaryContainerPages();
+  editSummaryTitles();
+  editSummaryAfterInterfaces();
+  deleteOldGeneratedDocs();
+  moveNewGeneratedDocs();
+  deleteTempDirectory();
+  replaceText(baseFolder);
+};
+
+main();

build-docs.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+
+root_path="src" # this could be src/interfaces
+
+# generate docs in a temporary directory
+temp_folder="technical-docs"
+
+# path to the base folder
+base_folder="docs/src/$root_path"
+
+FOUNDRY_PROFILE=docs forge doc --out "$temp_folder"
+
+# edit generated summary not to have container pages
+# - [jobs](src/interfaces/jobs/README.md)
+# should become
+# - [jobs]()
+# TODO
+
+# edit generated summary titles to start with an uppercase letter
+# - [jobs]()
+# should become
+# - [Jobs]()
+# TODO
+
+# edit the SUMMARY after the Interfaces section
+# https://stackoverflow.com/questions/67086574/no-such-file-or-directory-when-using-sed-in-combination-with-find
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  sed -i '' -e '/\Technical Documentation/q' docs/src/SUMMARY.md
+else
+  sed -i -e '/\Technical Documentation/q' docs/src/SUMMARY.md
+fi
+# copy the generated SUMMARY, from the tmp directory, without the first 5 lines
+# and paste them after the Interfaces section on the original SUMMARY
+tail -n +4 $temp_folder/src/SUMMARY.md >> docs/src/SUMMARY.md
+
+# delete old generated interfaces docs
+rm -rf docs/src/$root_path
+# there are differences in cp and mv behavior between UNIX and macOS when it comes to non-existing directories
+# creating the directory to circumvent them
+mkdir -p docs/src/$root_path
+# move new generated interfaces docs from tmp to original directory
+cp -R $temp_folder/src/$root_path docs/src
+
+# delete tmp directory
+rm -rf $temp_folder
+
+# function to replace text in all files (to fix the internal paths)
+replace_text() {
+    for file in "$1"/*; do
+        if [ -f "$file" ]; then
+            sed -i "s|$temp_folder/src/||g" "$file"
+        elif [ -d "$file" ]; then
+            replace_text "$file"
+        fi
+    done
+}
+
+# calling the function to fix the paths
+replace_text "$base_folder"

package.json

@@ -16,6 +16,8 @@
     "coverage": "forge coverage --match-contract Unit",
     "deploy:goerli": "bash -c 'source .env && forge script DeployGoerli --rpc-url $GOERLI_RPC --broadcast --private-key $GOERLI_DEPLOYER_PK --verify --etherscan-api-key $ETHERSCAN_API_KEY'",
     "deploy:mainnet": "bash -c 'source .env && forge script DeployMainnet --rpc-url $MAINNET_RPC --broadcast --private-key $MAINNET_DEPLOYER_PK --verify --etherscan-api-key $ETHERSCAN_API_KEY'",
+    "docs:build": "./build-docs.sh",
+    "docs:run": "mdbook serve docs",
     "lint:check": "yarn lint:sol-tests && yarn lint:sol-logic && forge fmt --check",
     "lint:fix": "sort-package-json && forge fmt && yarn lint:sol-tests --fix && yarn lint:sol-logic --fix",
     "lint:sol-logic": "solhint -c .solhint.json 'solidity/contracts/**/*.sol' 'solidity/interfaces/**/*.sol'",