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

Basic Usage

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

• Tetsuo Koyama for ideas, code, doc, security, maintenance

• All Contributors for doc

• pre-commit.ci for maintenance

Using Profile Links

The :profile: option makes contributor names clickable links to their profile URLs:

.. all-contributors:: ../.all-contributorsrc
   :profile:

• Tetsuo Koyama for ideas, code, doc, security, maintenance

• All Contributors for doc

• pre-commit.ci for maintenance

Using Table Format

The :table: option displays contributors in a table format instead of a bullet list:

.. all-contributors:: ../.all-contributorsrc
   :table:

Name	Contributions
Tetsuo Koyama	ideas, code, doc, security, maintenance
All Contributors	doc
pre-commit.ci	maintenance

Using Avatar Icons

The :avatar: option displays contributor avatar/profile images from the avatar_url field:

.. all-contributors:: ../.all-contributorsrc
   :avatar:

• Tetsuo Koyama for ideas, code, doc, security, maintenance

• All Contributors for doc

• pre-commit.ci for maintenance

Using Emoji Icons

The :emoji: option displays emoji icons before contribution types based on the all-contributors emoji key:

.. all-contributors:: ../.all-contributorsrc
   :emoji:

• Tetsuo Koyama for 🤔 ideas, 💻 code, 📖 doc, 🛡️ security, 🚧 maintenance

• All Contributors for 📖 doc

• pre-commit.ci for 🚧 maintenance

Combining Options

You can combine :table:, :profile:, :avatar:, and :emoji: options:

.. all-contributors:: ../.all-contributorsrc
   :table:
   :profile:

Name	Contributions
Tetsuo Koyama	ideas, code, doc, security, maintenance
All Contributors	doc
pre-commit.ci	maintenance

.. all-contributors:: ../.all-contributorsrc
   :profile:
   :avatar:

• Tetsuo Koyama for ideas, code, doc, security, maintenance

• All Contributors for doc

• pre-commit.ci for maintenance

.. all-contributors:: ../.all-contributorsrc
   :profile:
   :emoji:

• Tetsuo Koyama for 🤔 ideas, 💻 code, 📖 doc, 🛡️ security, 🚧 maintenance

• All Contributors for 📖 doc

• pre-commit.ci for 🚧 maintenance