docs: Add pagetoc to API docs

.github/workflows/ci-docs.yaml

@@ -81,13 +81,11 @@ jobs:
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1
 
+      - name: Install forge doc deps
+        run: cargo install mdbook-pagetoc
+
       - 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/+/+"
+        run: pnpm doc
 
       - name: Deploy to api-reference branch
         uses: peaceiris/actions-gh-pages@v3

.github/workflows/contracts-test.yaml

@@ -56,6 +56,8 @@ jobs:
             ${{ runner.os }}-pnpm-store-
       - name: Install Foundry
         uses: foundry-rs/foundry-toolchain@v1
+      - name: Install forge doc deps
+        run: cargo install mdbook-pagetoc
       - name: Install dependencies
         run: pnpm install
       - name: Build JS client
@@ -69,8 +71,7 @@ jobs:
         run: pnpm hardhat test --network sapphire-localnet-ci
       - name: Build docs
         working-directory: contracts
-        run: |
-          forge doc --build
+        run: 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

@@ -18,7 +18,7 @@ $ pnpm install @oasisprotocol/sapphire-contracts
 
 #### Usage
 
-Once installed, you can import and use the Sapphire contracts as follows.
+Once installed, you can import and use the Sapphire contracts as follows:
 
 ```solidity
 pragma solidity ^0.8.13;
@@ -37,7 +37,19 @@ 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).
+The generated API reference is hosted at
+[api.docs.oasis.io](https://api.docs.oasis.io/sol/sapphire-contracts).
+
+Generating API docs locally requires Foundry and mdbook-pagetoc. To install
+them and generate the docs execute:
+
+```shell
+curl -L https://foundry.paradigm.xyz | bash
+cargo install mdbook-pagetoc
+pnpm doc
+```
+
+The API docs index will be located in `sol/sapphire-contracts/book/index.html`.
 
 ## Contribute
 

contracts/book.toml

@@ -0,0 +1,4 @@
+[preprocessor.pagetoc]
+[output.html]
+additional-css = ["theme/pagetoc.css"]
+additional-js  = ["theme/pagetoc.js"]

contracts/package.json

@@ -9,6 +9,7 @@
     "url": "https://github.com/oasisprotocol/sapphire-paratime.git"
   },
   "scripts": {
+    "doc": "forge doc --build && ./post-build-doc.sh",
     "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'",

contracts/post-build-doc.sh

@@ -0,0 +1,12 @@
+#!/bin/sh
+
+# This script is to be executed by `pnpm doc` after building the docs.
+
+# 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

contracts/theme/pagetoc.css

@@ -0,0 +1,58 @@
+@media only screen and (max-width:1439px) {
+    .sidetoc {
+        display: none;
+    }
+}
+
+@media only screen and (min-width:1440px) {
+    main {
+        position: relative;
+    }
+    .sidetoc {
+        margin-left: auto;
+        margin-right: auto;
+        left: calc(100% + (var(--content-max-width))/4 - 140px);
+        position: absolute;
+    }
+    .pagetoc {
+	font-size: 12px;
+        position: fixed;
+        width: 220px;
+        height: calc(100vh - var(--menu-bar-height) - 0.67em * 4);
+        overflow: auto;
+    }
+    .pagetoc a {
+        border-left: 1px solid var(--sidebar-bg);
+        color: var(--fg) !important;
+        display: block;
+        padding-bottom: 5px;
+        padding-top: 5px;
+        padding-left: 10px;
+        text-align: left;
+        text-decoration: none;
+    }
+    .pagetoc a:hover,
+    .pagetoc a.active {
+        background: var(--sidebar-bg);
+        color: var(--sidebar-fg) !important;
+    }
+    .pagetoc .active {
+        background: var(--sidebar-bg);
+        color: var(--sidebar-fg);
+    }
+    .pagetoc .pagetoc-H2 {
+        padding-left: 20px;
+    }
+    .pagetoc .pagetoc-H3 {
+        padding-left: 40px;
+    }
+    .pagetoc .pagetoc-H4 {
+	display: none;
+    }
+    .pagetoc .pagetoc-H5 {
+        display: none;
+    }
+    .pagetoc .pagetoc-H6 {
+        display: none;
+    }
+}