Examples - sphinx-contributors documentation

Skip to content
Back to top
View this page

# Examples

The `contributors` directive renders the contributors of a given GitHub repository in a Sphinx documentation page. This page shows the different options available.

## Basic usage

List the contributors from a repository:

    .. contributors:: dgarcia360/sphinx-contributors

- dgarcia360

- dependabot[bot]

- jdillard

- stefmolin

- tsvi

- segfaultxavi

- sciencewhiz

## With avatars

Display contributor avatars:

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

- dgarcia360

- dependabot[bot]

- jdillard

- stefmolin

- tsvi

- segfaultxavi

- sciencewhiz

## Avatars only

Show only clickable avatars with no text. Hover over an avatar to see the username:

    .. contributors:: dgarcia360/sphinx-contributors
       :avatars_only:

## With contribution counts

Show how many contributions each user has made:

    .. contributors:: dgarcia360/sphinx-contributors
       :contributions:

- dgarcia360

  60 contributions

- dependabot[bot]

  6 contributions

- jdillard

  5 contributions

- stefmolin

  1 contribution

- tsvi

  1 contribution

- segfaultxavi

  1 contribution

- sciencewhiz

  1 contribution

## With real names

Show real names instead of usernames (fetched from GitHub profiles):

    .. contributors:: dgarcia360/sphinx-contributors
       :names:

- David Garcia

- dependabot[bot]

- Jared Dillard

- Stefanie Molin

- Tsvi Mostovicz

- Xavi Artigas

- sciencewhiz

## Excluding users

Exclude bots or specific users:

    .. contributors:: dgarcia360/sphinx-contributors
       :exclude: dependabot[bot], pre-commit-ci[bot]

- dgarcia360

- jdillard

- stefmolin

- tsvi

- segfaultxavi

- sciencewhiz

## Including additional contributors

Manually add contributors not detected by the API (e.g., `Co-authored-by` contributors):

    .. contributors:: dgarcia360/sphinx-contributors
       :include: Peque

- dgarcia360

- dependabot[bot]

- jdillard

- stefmolin

- tsvi

- segfaultxavi

- sciencewhiz

- Peque

## Multiple repositories

Merge contributors from multiple repositories into a single list. Contribution counts are summed for users who appear in more than one repository:

    .. contributors:: dgarcia360/sphinx-contributors sphinx-doc/sphinx
       :contributions:
       :limit: 10

- tk0miya

  9123 contributions

- birkenfeld

  3499 contributions

- AA-Turner

  1821 contributions

- jfbu

  1494 contributions

- shimizukawa

  895 contributions

- jakobandersen

  584 contributions

- DasIch

  224 contributions

- stephenfin

  183 contributions

- lehmannro

  140 contributions

- jacobmason

  134 contributions

## Limiting and sorting

Control how many contributors are shown and in what order:

    .. contributors:: dgarcia360/sphinx-contributors
       :contributions:
       :limit: 3
       :order: ASC

- stefmolin

  1 contribution

- tsvi

  1 contribution

- segfaultxavi

  1 contribution

## Combining options

Avatars, real names, and contribution counts together:

    .. contributors:: dgarcia360/sphinx-contributors
       :avatars:
       :names:
       :exclude: dependabot[bot]

- David Garcia

- Jared Dillard

- Stefanie Molin

- Tsvi Mostovicz

- Xavi Artigas

- sciencewhiz

For more information on how to style the list, see Customization.