contracts: Compile API reference docs

.github/workflows/ci-docs.yaml

@@ -4,6 +4,7 @@ on:
   push:
     paths:
       - clients/js/**
+      - contracts/**
     branches:
       - main
 
@@ -67,3 +68,34 @@ jobs:
           user_name: github-actions[bot]
           user_email: 41898282+github-actions[bot]@users.noreply.github.com
 
+  sol-docs:
+    name: sol-docs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./contracts
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Build docs
+        run: |
+          forge doc --build
+          # Inject another /contracts/ for github.com URLs.
+          find sol/sapphire-contracts/book -name *.html | xargs sed -i -E "s+(blob/.*/contracts)+\1/contracts+"
+          # Remove /src/ from "Inherits" links.
+          find sol/sapphire-contracts/book -name *.html | xargs sed -i "s+/src/+/+"
+
+      - name: Deploy to api-reference branch
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: contracts/sol/sapphire-contracts/book
+          publish_branch: api-reference
+          destination_dir: sol/sapphire-contracts
+          commit_message: Deploy sol API reference ${{ github.event.head_commit.message }}
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/contracts-test.yaml

@@ -49,6 +49,8 @@ jobs:
           key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
           restore-keys: |
             ${{ runner.os }}-pnpm-store-
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
       - name: Install dependencies
         run: pnpm install
       - name: Build JS client
@@ -60,6 +62,10 @@ jobs:
       - name: hardhat test contracts
         working-directory: contracts
         run: pnpm hardhat test --network sapphire-dev-ci
+      - name: Build docs
+        working-directory: contracts
+        run: |
+          forge doc --build
       - name: hardhat test examples/truffle
         working-directory: examples/truffle
         run: pnpm run test --network sapphire_localnet

contracts/README.md

@@ -26,8 +26,12 @@ import {Enclave} from "@oasisprotocol/sapphire-contracts/contracts/OPL.sol";
 
 ## Documentation
 
-See documentation for [Sapphire](https://docs.oasis.io/dapp/sapphire/) and [OPL](https://docs.oasis.io/dapp/opl/).
+See the user's guide for [Sapphire](https://docs.oasis.io/dapp/sapphire/) and
+[OPL](https://docs.oasis.io/dapp/opl/).
+
+API reference is available at [api.docs.oasis.io](https://docs.oasis.io/sol/sapphire-contracts).
 
 ## Contribute
 
-There are many ways you can participate and help build high quality software. Check out the [contribution guide](../CONTRIBUTING.md)!
+There are many ways you can participate and help build high quality software.
+Check out the [contribution guide](https://github.com/oasisprotocol/sapphire-paratime/blob/main/CONTRIBUTING.md)!

contracts/foundry.toml

@@ -0,0 +1,4 @@
+[doc]
+out = "sol/sapphire-contracts"
+title = "Sapphire Contracts Lib"
+ignore = ["contracts/tests/*"]