Foundry has a built-in documentation feature that generates an mdbook for all contracts in the src directory. NATSPEC comments are used to populate the content. This can then be built using GitHub Actions and hosted using GitHub pages.
The default configuration is ok, but I've customized it with a GitHub action which on every push to the repo:
Builds the updated docs.
Customizes the config.
Commits the changes to the documentation branch gh-pages.
Publishes the updated docs on GitHub pages.
Viewing Locally
To view the site locally run:
forge doc --build --serve --port=4000
This won't have the config customizations made using the GitHub Actions workflow, but it can be useful for local development.
GitHub Actions Workflow
Create a workflow .yml file at .github/workflows/deployGitHubPages.yml
Modify:
<ADD_TITLE_HERE>
<ADD_AUTHOR_HERE>
.github/workflows/deployGitHubPages.yml
name: Deploy Docs to GitHub Pages
on: [push]
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Checkout
uses: actions/checkout@v4
with:
submodules: recursive
- name: Install Foundry
uses: foundry-rs/foundry-toolchain@v1
- name: Install Dependencies
run: forge install
- name: Generate Documentation
run: forge doc
- name: Edit book.toml
run: |
sed -i 's/title = ""/title = "<ADD_TITLE_HERE>"/' ./docs/book.toml # Set the title of the book
sed -i 's/authors = \[\]/authors = \["<ADD_AUTHOR_HERE>"\]/' ./docs/book.toml # Set the author of the book
sed -i '/\[book\]/a language = "en"' ./docs/book.toml # Add language setting under [book]
sed -i '/\[book\]/a multilingual = false' ./docs/book.toml # Add multilingual setting under [book]
sed -i 's/no-section-label = true/no-section-label = false/' ./docs/book.toml # Change no-section-label to false
sed -i '/\[output.html\]/a default-theme = "dark"' ./docs/book.toml # Add default-theme under [output.html]
sed -i '/\[output.html\]/a preferred-dark-theme = "ayu"' ./docs/book.toml # Add preferred-dark-theme under [output.html]
sed -i '/^\[output.html.fold\]$/,/^\[/ s/^enable = true/enable = false/' ./docs/book.toml # Change enable under [output.html.fold]
- name: Edit SUMMARY.md
run: |
sed -i 's/❱ //g' ./docs/src/SUMMARY.md # Removes the "❱ " from lines
sed -i '/^# src$/d' ./docs/src/SUMMARY.md # Deletes the line containing exactly "# src"
sed -i 's/- \[Home\](README.md)/[README](README.md)/' ./docs/src/SUMMARY.md # Replaces "- [Home](README.md)" with "[README](README.md)"
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Install mdbook
run: |
mkdir mdbook
curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.36/mdbook-v0.4.36-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook
echo `pwd`/mdbook >> $GITHUB_PATH
- name: Build book
run: |
cd ./docs
mdbook build
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/book
GitHub Pages Repo Settings
The branch gh-pages is created by the Actions workflow, so this step can only be completed after the Action has run successfully for the first time.
