Installation - sphinx-contributors documentation

Skip to content
Back to top
View this page

# Installation

Important

sphinx-contributors is compatible with Sphinx 7.0+ using Python 3.10+.

## Getting started

Follow these steps to add sphinx-contributors to your Sphinx project:

1. Install `sphinx-contributors` using PIP.

       pip install sphinx-contributors

2. Add the extension to your Sphinx project `conf.py` file.

       extensions = ['sphinx_contributors']

3. Add a `contributors` directive to any `.rst` file.

       .. contributors:: dgarcia360/sphinx-contributors
          :avatars:

   This renders all contributors with their avatars (use `:limit:` to show fewer):

   - dgarcia360

   - dependabot[bot]

   - jdillard

   - stefmolin

   - tsvi

   - segfaultxavi

   - sciencewhiz

   See Examples for all available options.

## GitHub API rate limits

This extension uses the GitHub REST API. Unauthenticated requests are limited to 60 per hour. Each `contributors` directive makes at least one API call, and options like `:names:` or `:include:` make additional calls per contributor. If you hit the rate limit, contributor lists will appear empty until it resets.

To increase the limit to 5,000 requests per hour, set a `GITHUB_TOKEN` environment variable with a GitHub personal access token. A fine-grained token with no extra permissions is sufficient for public repositories.

    # Locally
    export GITHUB_TOKEN=ghp_your_token_here

For CI/CD environments like ReadTheDocs, add the token as an environment variable in your project settings. For GitHub Actions, use a repository secret:

    - name: Build docs
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      run: make -C docs dirhtml