sphinx-all-contributors

sphinx-all-contributors is a Sphinx extension that allows you to easily display a list of contributors from a .all-contributorsrc file in your Sphinx documentation. The list is generated in a simple, readable format like:

- Contributor Name 1 for ideas, docs
- Contributor Name 2 for code

Features

• Automatically reads the list of contributors from a .all-contributorsrc file.
• Customizable relative path to the .all-contributorsrc file.
• Outputs a list of contributors in a clean, human-readable format.

Installation

pip install sphinx-all-contributors

Usage

Add sphinx-all-contributors to the extensions list in your conf.py:

# conf.py
extensions = [
    "sphinx_all_contributors",
    # other extensions
]

Create a .all-contributorsrc file in your documentation source directory (or another location). You can create this file manually following the all-contributors format, or you can use the all-contributors bot to automate this process and ensure that your contributor data is accurate and up-to-date. An example .all-contributorsrc file looks like this:

{
  "contributors": [
    {
      "name": "Contributor Name 1",
      "contributions": ["ideas", "docs"]
    },
    {
      "name": "Contributor Name 2",
      "contributions": ["code"]
    }
  ]
}

In your .rst file, use the all-contributors directive to display the list of contributors. You can specify the relative path to the .all-contributorsrc file or omit it to use the default path (.all-contributorsrc in the source directory).

Example 1: Using the default .all-contributorsrc path:

.. all-contributors::

Example 2: Specifying a relative path to the .all-contributorsrc file:

.. all-contributors:: config/.all-contributorsrc

Build your documentation:

make html

The generated HTML (or other formats) will contain a list of contributors in the format:

- Contributor Name 1 for ideas, docs
- Contributor Name 2 for code