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

Table of Contents

• Install
• Usage
• Features
• Options
• Contributing
• License

Install

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

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.
• Optional emoji display for contribution types using the :emoji: flag.
• Optional profile links for contributors using the :profile: flag.

Options

The all-contributors directive supports the following options:

:profile: flag

Makes contributor names clickable links to their profile URLs (if profile URLs are available in the .all-contributorsrc file).

Example:

.. all-contributors::
   :profile:

Output:

- [Contributor Name 1](profile-url) for ideas, docs
- [Contributor Name 2](profile-url) for code

:emoji: flag

Displays emoji icons before contribution types based on the all-contributors emoji key.

Example:

.. all-contributors::
   :emoji:

Output:

- Contributor Name 1 for 🤔 ideas, 📖 docs
- Contributor Name 2 for 💻 code

You can combine both options:

.. all-contributors::
   :profile:
   :emoji:

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

MIT