crytic / slither-docs-action

Write documentation for your code in pull requests using Slither and OpenAI.

Document with Slither

Documenting your code can be tiresome. This action will help you write documentation for your code in pull requests using Slither and OpenAI. Just label your PR with generate-docs and the action will get it done!

You can see an example repository integrating this action here: crytic/slither-docs-demo. An example pull request showing the workflow in action is also available on that repository.

Note

As this action pushes the documentation to the same pull request branch, it only works on pull requests from the same repository. If you trigger the workflow on a pull request originating from a fork, it will display an error.

Usage

This action needs to be run on a pull_request event of type labeled. The workflow needs to have contents: write permissions (to push documentation commits to your PR) and pull-requests: write permissions (to untag and leave comments on your PR)

You will also need an OpenAI API key. You can create one in the OpenAI website, by clicking on your profile picture, followed by the "View API keys" link.

Warning

This action will transmit code from your repository to OpenAI during normal operation. Review OpenAI's terms of service and privacy policy to see how your data will be processed, used, or stored.

Once you have acquired your API key, store it as an Actions secret for the GitHub repository. You may follow the instructions in the GitHub documentation to do so.

Warning

The OpenAI API is a paid service. The requests that Slither performs to OpenAI's API endpoints cost money. Make sure you trust all the contributors with access to your repository, which may invoke this action with your API key. Configure adequate cost limits and alerts in OpenAI to avoid unexpected bills.

- name: Document with Slither
  uses: crytic/slither-docs-action@v0
  with:
    target: project
    openai-api-key: ${{ secrets.OPENAI_API_KEY }}

Options

Key	Description
target	The path to the root of the project to be documented by Slither. It can be a directory or a file, and it defaults to the repo root.
openai-api-key	The OpenAI API key.
trigger-label	The label used to trigger the action. generate-docs by default.
slither-version	The version of slither-analyzer to use. By default, the latest release in PyPI is used.
solc-version	The version of solc to use. This only has an effect if you are not using a compilation framework for your project -- i.e., if target is a standalone .sol file.
github-token	GitHub token, used to compute PR differences and push documentation. By default, it will use the workflow token, and there should be no need to override it.

Examples

These examples assume you have a valid OpenAI API key stored as a secret named OPENAI_API_KEY in your GitHub repository.

Example: Hardhat

name: Document with Slither

on:
  pull_request:
    types: [labeled]
    branches: [main]

jobs:
  document:
    name: Document with Slither
    runs-on: ubuntu-latest
    if: contains(github.event.pull_request.labels.*.name, 'generate-docs')
    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup Node.js 16.x
        uses: actions/setup-node@v3
        with:
          node-version: 16

      - name: Install dependencies
        working-directory: project
        run: npm ci

      - name: Document with Slither
        uses: crytic/slither-docs-action@v0
        with:
          target: project
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}

Example: Foundry

name: Document with Slither

on:
  pull_request:
    types: [labeled]
    branches: [main]

jobs:
  document:
    name: Document with Slither
    runs-on: ubuntu-latest
    if: contains(github.event.pull_request.labels.*.name, 'generate-docs')
    permissions:
      contents: write
      pull-requests: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install Foundry
        uses: foundry-rs/foundry-toolchain@v1

      - name: Document with Slither
        uses: crytic/slither-docs-action@v0
        with:
          target: project
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}