feat: add build-docs.sh

.github/workflows/docs.yml

@@ -8,11 +8,10 @@ on:
 
 jobs:
   deploy-docs:
-    if: github.repository == 'hai-on-op/hai'
+    # Remove the following line if you wish to export your Solidity contracts and interfaces and publish them to NPM
+    if: false
     name: Deploy docs
     runs-on: ubuntu-latest
-    environment:
-      name: ${{ github.ref_name == 'main' && 'Prod' || 'Dev' }}
 
     steps:
       - uses: actions/checkout@v3
@@ -23,7 +22,7 @@ jobs:
       - name: Install node
         uses: actions/setup-node@v3
         with:
-          node-version: ${{ matrix.node-version }}
+          node-version: 18.x
           cache: 'yarn'
 
       - name: Install dependencies

build-docs.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+
+root_path="src" # this could be src/interfaces
+# generate docs in a temporary directory
+temp_folder="technical-docs"
+
+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
+}
+
+# path to the base folder
+base_folder="docs/src/$root_path"
+
+# 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'",