ci: build and push evm contract docs to github pages (#211)

Co-authored-by: Milap Sheth <milap@interoplabs.io>

.github/actions/upload-docs/action.yaml

@@ -0,0 +1,54 @@
+name: "Upload Docs"
+
+description: "Build and upload docs to GitHub Pages"
+inputs:
+  branches:
+    description: "Branches to trigger the workflow on"
+    required: false
+    default: "main"
+  environment_name:
+    description: "Name of the deployment environment"
+    required: false
+    default: "github-pages"
+  script:
+    description: 'The script to run for generating documentation'
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Create docs directory
+      run: mkdir -p docs
+      shell: bash
+
+    - name: Build Solidity documentation
+      run: npx hardhat docgen
+      shell: bash
+
+    - name: Generate Overview Documentation
+      run: node ${{ inputs.script }}
+      shell: bash
+
+    - name: Verify docs directory is not empty
+      run: |
+        if [ ! -d "docs" ] || [ ! -s "docs/index.md" ]; then
+          echo "Docs directory is empty or does not exist"
+          exit 1
+        fi
+      shell: bash
+
+    - name: Add YAML front matter for Jekyll
+      run: |
+        find docs -name '*.md' -exec sh -c 'sed -i.bak "1s/^/---\nlayout: default\n---\n/" "$0" && rm "$0.bak"' {} \;
+      shell: bash
+
+    - name: Setup Github Pages
+      uses: actions/configure-pages@v5
+
+    - name: Build with Jekyll
+      uses: actions/jekyll-build-pages@v1
+      with:
+        source: ./docs
+
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3

.github/workflows/upload-contract-docs.yaml

@@ -0,0 +1,42 @@
+name: Upload Contract Docs
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  upload-docs:
+    runs-on: blacksmith-2vcpu-ubuntu-2204
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup tools
+        uses: ./.github/actions/setup-tools
+        with:
+          install-nodejs: 'true'
+
+      - name: Run Upload Docs Action
+        uses: axelarnetwork/axelar-gmp-sdk-solidity/.github/actions/upload-docs@main
+        with:
+          branches: main
+          environment_name: github-pages
+          script: scripts/generateOverviewDocs.js
+
+  deploy:
+    needs: upload-docs
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: blacksmith-2vcpu-ubuntu-2204
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

contracts/governance/BaseWeightedMultisig.sol

@@ -23,15 +23,12 @@ abstract contract BaseWeightedMultisig is IBaseWeightedMultisig {
     }
 
     /// @dev Previous signers retention. 0 means only the current signers are valid
-    /// @return The number of epochs to keep the signers valid for signature verification
     uint256 public immutable previousSignersRetention;
 
     /// @dev The domain separator for the signer proof
-    /// @return The domain separator for the signer proof
     bytes32 public immutable domainSeparator;
 
     /// @dev The minimum delay required between rotations
-    /// @return The minimum delay required between rotations
     uint256 public immutable minimumRotationDelay;
 
     /**

hardhat.config.js

@@ -1,5 +1,6 @@
 require('@nomicfoundation/hardhat-toolbox');
 require('solidity-coverage');
+require('solidity-docgen');
 
 if (process.env.STORAGE_LAYOUT) {
     require('hardhat-storage-layout');
@@ -102,4 +103,9 @@ module.exports = {
         strict: process.env.CHECK_CONTRACT_SIZE,
         except: ['contracts/test'],
     },
+    docgen: {
+        path: 'docs',
+        clear: true,
+        pages: 'files',
+    },
 };

index.js

@@ -28,6 +28,7 @@ const {
     upgradeUpgradable,
 } = require('./scripts/upgradable');
 const { printObj } = require('./scripts/utils');
+const { generateDocsIndex } = require('./scripts/generateOverviewDocs');
 
 module.exports = {
     estimateGasForDeploy,
@@ -54,4 +55,5 @@ module.exports = {
     deployCreate3InitUpgradable,
     upgradeUpgradable,
     printObj,
+    generateDocsIndex,
 };

package.json

@@ -16,7 +16,8 @@
     "release-snapshot": "npm run build && npm run flatten && npm run clean:artifacts && npm version 0.0.0-snapshot.$(git rev-parse --short HEAD) --git-tag-version=false && npm publish --no-git-checks --tag snapshot --access public",
     "cs": "changeset",
     "flatten": "sh scripts/flatten-contracts.sh",
-    "coverage": "cross-env COVERAGE=true hardhat coverage"
+    "coverage": "cross-env COVERAGE=true hardhat coverage",
+    "generate-overview-docs": "node scripts/generateOverviewDocs.js"
   },
   "author": "axelar-network",
   "license": "MIT",
@@ -35,7 +36,8 @@
     "mocha": "^10.2.0",
     "prettier": "^2.8.8",
     "prettier-plugin-solidity": "1.0.0-beta.19",
-    "solhint": "^4.5.2"
+    "solhint": "^4.5.2",
+    "solidity-docgen": "^0.6.0-beta.36"
   },
   "engines": {
     "node": ">=18"