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