Automate Smart Contracts documentation publishing (#1779)

* Enable docgen for legacy market

* Delete pre-generated docs

* Add docs dirs to gitignore

* Remove diff check

* Enable legacy market docs in combined file

* Disable tests

* CCI docgen

* Store docgen in artifacts

* git

* Run docgen

* Enable tests

* ABIs are now moved to synthetix docs v3 repo

* Halt if no changes to docs

* Generate ABIs and docs page

* Cache SOLC

* Remove TOC as gitbook auto-generates it

* Use local IPFS with cannon

* Fail on errors

* Deps

* Fix missing deployments folder

* Install Foundry and Anvil

* Less verbose

.circleci/config.yml

@@ -0,0 +1,205 @@
+version: 2.1
+
+parameters:
+  node-version:
+    type: string
+    default: "16.20.1"
+
+commands:
+  yarn-install:
+    steps:
+      - run: yarn install --immutable --immutable-cache
+
+  install-foundry:
+    steps:
+      - restore_cache:
+          keys:
+            - foundry-{{ .Environment.FOUNDRY_CACHE_VERSION }}
+
+      - run:
+          name: "Install Foundry"
+          working_directory: ~/
+          environment:
+            SHELL: /bin/bash
+          command: |-
+            export PATH="$PATH:$HOME/.foundry/bin"
+            echo 'export PATH=$PATH:$HOME/.foundry/bin' >> $BASH_ENV
+
+            if command -v anvil; then
+              echo "Anvil already installed"
+              anvil --version
+            else
+              curl -L https://foundry.paradigm.xyz | bash
+              foundryup
+            fi
+
+      - save_cache:
+          key: foundry-{{ .Environment.FOUNDRY_CACHE_VERSION }}
+          paths:
+            - "~/.foundry"
+
+  install-ipfs:
+    steps:
+      - restore_cache:
+          keys:
+            - ipfs-{{ .Environment.IPFS_CACHE_VERSION }}
+
+      - run:
+          name: "Install IPFS"
+          working_directory: ~/
+          command: |
+            export PATH="$PATH:$HOME/go-ipfs"
+            echo 'export PATH=$PATH:$HOME/go-ipfs' >> $BASH_ENV
+
+            if command -v ipfs; then
+              echo "IPFS already installed"
+              ipfs version
+              ipfs id
+            else
+              LATEST_VERSION=$(curl -sSL https://dist.ipfs.tech/go-ipfs/versions | tail -n 1)
+              LATEST_VERSION_NUMBER=${LATEST_VERSION#*v}
+              DOWNLOAD_URL="https://dist.ipfs.tech/go-ipfs/${LATEST_VERSION}/go-ipfs_${LATEST_VERSION}_linux-amd64.tar.gz"
+              echo "DOWNLOAD_URL=$DOWNLOAD_URL"
+              curl -sSL -o ipfs.tar.gz $DOWNLOAD_URL
+              tar -xzf ipfs.tar.gz
+              rm -rf ~/.ipfs
+              ipfs init
+            fi
+
+      - save_cache:
+          key: ipfs-{{ .Environment.IPFS_CACHE_VERSION }}
+          paths:
+            - "~/go-ipfs"
+            - "~/.ipfs"
+
+  run-ipfs-daemon:
+    steps:
+      - run:
+          command: ipfs daemon
+          background: true
+
+  wait-for-ipfs:
+    steps:
+      - run:
+          name: "Wait for IPFS daemon to start"
+          command: wget --retry-connrefused --waitretry=20 --read-timeout=20 --timeout=15 -t 10 --post-data '' "http://localhost:5001/api/v0/version"
+
+jobs:
+  docgen:
+    docker:
+      - image: cimg/node:<< pipeline.parameters.node-version >>
+    environment:
+      - CANNON_IPFS_URL: "http://127.0.0.1:5001"
+      - CANNON_PUBLISH_IPFS_URL: "http://127.0.0.1:5001"
+      - GIT_PAGER: cat
+    working_directory: ~/synthetix-v3
+    steps:
+      - add_ssh_keys:
+          fingerprints: "46:05:bf:bf:84:e8:af:09:35:05:89:09:62:45:84:7c"
+      - run:
+          working_directory: ~/
+          name: "Checkout docs"
+          command: |
+            ssh-keyscan github.com >> ~/.ssh/known_hosts
+            git clone git@github.com:Synthetixio/Synthetix-Gitbook-v3.git --verbose --depth 1 --no-tags --single-branch synthetix-gitbook-v3
+
+      - checkout
+
+      - install-ipfs
+      - run-ipfs-daemon
+      - install-foundry
+      - yarn-install
+      - wait-for-ipfs
+
+      - run:
+          name: "Build TS"
+          command: yarn workspaces foreach --topological-dev --verbose run build:ts
+
+      - restore_cache:
+          keys:
+            - hardhat-{{ .Environment.SOLC_VERSION }}
+      - run:
+          name: "Generate docs for each contract"
+          command: yarn workspaces foreach --verbose run docgen
+      - save_cache:
+          key: hardhat-{{ .Environment.SOLC_VERSION }}
+          paths:
+            - "~/.cache/hardhat-nodejs"
+
+      - run:
+          name: "Generate combined smart-contracts.md"
+          working_directory: ~/synthetix-v3/utils/docgen
+          command: ./docgen-contracts.sh
+
+      - run:
+          name: "Generate combined addresses-+-abis.md"
+          working_directory: ~/synthetix-v3/utils/docgen
+          command: ./docgen-abis.sh
+
+      - store_artifacts:
+          path: "docs"
+          destination: "."
+
+      - run:
+          working_directory: ~/synthetix-gitbook-v3
+          name: "Update docs and push to smart-contracts branch"
+          command: |
+            cp ~/synthetix-v3/docs/smart-contracts.md ./for-developers/smart-contracts.md
+            cp ~/synthetix-v3/docs/addresses-+-abis.md ./for-developers/addresses-+-abis.md
+            cp ~/synthetix-v3/docs/abis/*.json ./for-developers/abis/
+
+            STATUS=$(git status)
+            if [[ $STATUS == *"nothing to commit, working tree clean"* ]]; then
+              echo "SKIP. Working tree is clean. No changes to Smart Contracts docs"
+              exit 0
+            fi
+
+            git branch smart-contracts
+            git checkout smart-contracts
+
+            git config --global user.email nikita@cc.snxdao.io
+            git config --global user.name Noisekit
+
+            git add ./for-developers/smart-contracts.md
+            git add ./for-developers/addresses-+-abis.md
+            git add ./for-developers/abis
+            git commit -m "Update Smart Contracts"
+            git push --set-upstream --force origin smart-contracts
+
+            PR_URL=$(curl -s -H "Authorization: token $GITHUB_TOKEN" \
+              https://api.github.com/repos/Synthetixio/Synthetix-Gitbook-v3/pulls?state=open | \
+              jq -r '.[] | select(.head.ref=="smart-contracts") | .html_url')
+
+            # If no PR exists with the branch "smart-contracts", create one
+            # If PR already exists it would be updated with the most recent docs via forced push
+            if [ -z "$PR_URL" ]; then
+              curl -s -X POST -H "Authorization: token $GITHUB_TOKEN" \
+                https://api.github.com/repos/Synthetixio/Synthetix-Gitbook-v3/pulls \
+                -d '{
+                  "title": "Update Smart Contracts",
+                  "head": "smart-contracts", 
+                  "base": "en"
+                }'
+            else
+              echo "Pull Request already exists: $PR_URL"
+            fi
+
+workflows:
+  version: 2.1
+
+  docgen:
+    jobs:
+      - docgen:
+          name: "docgen-release"
+          filters:
+            tags:
+              only: /^v.*/
+            branches:
+              ignore: /.*/
+      - docgen:
+          name: "docgen-dev"
+          filters:
+            tags:
+              ignore: /.*/
+            branches:
+              only: /docgen/

.github/workflows/test.yml

@@ -2,6 +2,9 @@ name: Test
 
 on:
   pull_request: {}
+  push:
+    branches:
+      - "test"
 
 jobs:
   test:

.gitignore

@@ -17,6 +17,7 @@ node_modules
 Router.sol
 typechain-types
 lerna-debug.log
+docs/
 
 # Yarn v3
 .yarn/*