feat: mdbook docs

.gitignore

@@ -19,5 +19,10 @@ out/*/*
 # Keep the latest deployment only
 broadcast/*/*/*
 
+# Docs build files
+docs/book
+docs/src/solidity/interfaces
+docs/src/static
+
 # Cache for the python scripts
 proofs/__pycache__/*

build-docs.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# generate docs in a temporary directory
+FOUNDRY_PROFILE=docs forge doc --out tmp/safe-liveness-technical-docs
+
+# edit generated summary not to have container pages
+# - [jobs](solidity/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 '/\[Interfaces\]/q' docs/src/SUMMARY.md
+else
+  sed -i -e '/\[Interfaces\]/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 +5 tmp/safe-liveness-technical-docs/src/SUMMARY.md >> docs/src/SUMMARY.md
+
+# delete old generated interfaces docs
+rm -rf docs/src/solidity/interfaces
+# 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/solidity/interfaces
+# move new generated interfaces docs from tmp to original directory
+cp -R tmp/safe-liveness-technical-docs/src/solidity/interfaces docs/src/solidity/
+
+# delete tmp directory
+rm -rf tmp

docs/src/SUMMARY.md

@@ -0,0 +1,14 @@
+<!-- TODO: add links to oracles.rip, to mirror and to twitter -->
+
+# Overview
+
+- [Smart Contracts]()
+
+  - [Addresses](content/smart-contracts/addresses.md)
+  - [Interfaces]()
+    - [IBlockHeaderOracle](solidity/interfaces/IBlockHeaderOracle.sol/interface.IBlockHeaderOracle.md)
+    - [IGuardCallbackModule](solidity/interfaces/IGuardCallbackModule.sol/interface.IGuardCallbackModule.md)
+    - [ISafe](solidity/interfaces/ISafe.sol/interface.ISafe.md)
+    - [IStorageMirror](solidity/interfaces/IStorageMirror.sol/interface.IStorageMirror.md)
+    - [IStorageMirrorRootRegistry](solidity/interfaces/IStorageMirrorRootRegistry.sol/interface.IStorageMirrorRootRegistry.md)
+    - [IVerifierModule](solidity/interfaces/IVerifierModule.sol/interface.IVerifierModule.md)

docs/src/content/smart-contracts/addresses.md

@@ -0,0 +1 @@
+# Addresses

foundry.toml

@@ -28,6 +28,9 @@ out = 'out-via-ir'
 fuzz_runs = 5000
 src = 'solidity/test'
 
+[profile.docs]
+src = './solidity/interfaces/'
+
 [rpc_endpoints]
 mainnet = "${MAINNET_RPC}"
 goerli = "${GOERLI_RPC}"

package.json

@@ -17,6 +17,8 @@
     "deploy:mainnet": "bash -c 'source .env && forge script -vv --rpc-url $MAINNET_RPC --slow --broadcast --private-key $DEPLOYER_MAINNNET_PRIVATE_KEY solidity/scripts/DeployMainnet.s.sol:DeployMainnet'",
     "deploy:optimism": "bash -c 'source .env && forge script -vv --rpc-url $OPTIMISM_RPC --slow --broadcast --private-key $DEPLOYER_OPTIMISM_PRIVATE_KEY solidity/scripts/DeployOptimism.s.sol:DeployOptimism'",
     "deploy:optimismGoerli": "bash -c 'source .env && forge script -vv --rpc-url $OPTIMISM_GOERLI_RPC --slow --broadcast --private-key $DEPLOYER_OPTIMISM_GOERLI_PRIVATE_KEY solidity/scripts/DeployOptimismGoerli.s.sol:DeployOptimismGoerli'",
+    "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'",