contracts: Add doc rule to package.json

.github/workflows/ci-docs.yaml

@@ -86,13 +86,7 @@ jobs:
 
       - 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/+/+"
-          # Inject nicer Pagetoc theme (hides level-4 headings, smaller font, wider toc)
-          cp theme/* sol/sapphire-contracts/book/theme
+          pnpm doc
 
       - name: Deploy to api-reference branch
         uses: peaceiris/actions-gh-pages@v3

.github/workflows/contracts-test.yaml

@@ -72,7 +72,7 @@ jobs:
       - name: Build docs
         working-directory: contracts
         run: |
-          forge doc --build
+          pnpm doc
       - name: hardhat test examples/hardhat
         working-directory: examples/hardhat
         run: pnpm hardhat run --network sapphire-localnet scripts/run-vigil.ts

contracts/README.md

@@ -12,8 +12,8 @@
 
 #### Installation
 
-```solidity
-$ pnpm install @oasisprotocol/sapphire-contracts
+```shell
+pnpm install @oasisprotocol/sapphire-contracts
 ```
 
 #### Usage
@@ -37,7 +37,18 @@ contract RandomNumber {
 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://api.docs.oasis.io/sol/sapphire-contracts).
+Generated API reference is hosted at
+[api.docs.oasis.io](https://api.docs.oasis.io/sol/sapphire-contracts).
+
+To build API documentation with Foundry locally:
+
+```shell
+curl -L https://foundry.paradigm.xyz | bash
+cargo install mdbook-pagetoc
+forge doc --build
+```
+
+and open `sol/sapphire-contracts/book/index.html`.
 
 ## Contribute
 

contracts/package.json

@@ -9,6 +9,7 @@
     "url": "https://github.com/oasisprotocol/sapphire-paratime.git"
   },
   "scripts": {
+    "doc": "forge doc --build && find sol/sapphire-contracts/book -name *.html | xargs sed -i -E \"s+(blob/.*/contracts)+\\1/contracts+\" && find sol/sapphire-contracts/book -name *.html | xargs sed -i \"s+/src/+/+\" && cp theme/* sol/sapphire-contracts/book/theme",
     "lint:eslint": "eslint --ignore-path .gitignore --ext .ts",
     "lint:solhint": "solhint 'contracts/**/*.sol'",
     "lint::prettier": "prettier --cache --check --plugin-search-dir=. --cache '*.json' '**/*.ts' '**/*.sol'",