Reference - sphinx-contributors documentation

Skip to content
Back to top
View this page

# Reference

## Contributors directive

.. contributors:: username/repository [username/repository ...]

  One or more GitHub repositories, separated by spaces. When multiple repositories are specified, contributors are merged into a single list and contribution counts are summed for users who appear in more than one repository.

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

  :limit: (integer)

    Maximum number of contributors to list. If omitted, all contributors are shown.

  :order: (string)

    Results are sorted by the number of contributions. This parameter controls whether they are sorted by most active users first (`DESC`) or least active users first (`ASC`). Default is `DESC`.

  :avatars: (boolean)

    Whether to include an image with the avatar returned by GitHub. Use CSS to customize the image size, since the returned images might vary.

  :avatars_only: (boolean)

    Show only avatar images with no usernames or contribution counts. Each avatar links to the contributor’s GitHub profile, and the username is shown as a tooltip on hover. Implies `:avatars:`.

  :contributions: (boolean)

    Whether to show the total number of contributions by each user or not.

  :names: (boolean)

    Whether to display real names (fetched from GitHub user profiles) instead of usernames. Falls back to the username if the user has not set a name on their GitHub profile.

  :include: (string)

    Comma separated GitHub usernames to add to the list of contributors. This is useful for including people who contributed via `Co-authored-by` commit trailers, since the GitHub REST API does not count those as contributors. Already listed contributors are not duplicated. For example: `dgarcia360,otheruser`.

  :exclude: (string)

    Comma separated usernames to exclude from the list of contributors, for example: `dependabot[bot],pre-commit-ci[bot]`.

  Note

  The GitHub REST API used by this extension does not include contributors added via `Co-authored-by` commit trailers. Use the `:include:` option to manually add those contributors.