Skip to main content

Display a warning at the top of module documentation that it has additional requirements.

Project description

Display a warning at the top of module documentation that it has additional requirements.


Documentation Build Status Docs Check Status


Linux Test Status Windows Test Status macOS Test Status Coverage


PyPI - Package Version PyPI - Supported Python Versions PyPI - Supported Implementations PyPI - Wheel


Conda - Package Version Conda - Platform


GitHub last commit GitHub commits since tagged version Maintenance PyPI - Downloads


CodeFactor Grade Flake8 Status mypy status


License GitHub top language Requirements Status


This extension assumes you have a repository laid out like this:

├── chemistry_tools
│   ├──
│   ├── formulae
│   │   ├──
│   │   ├──
│   │   ├──
│   │   ├──
│   │   └── requirements.txt
│   ├──
│   └──
├── doc-source
│   ├── api
│   │   ├── chemistry_tools.rst
│   │   ├── elements.rst
│   │   ├── formulae.rst
│   │   └── pubchem.rst
│   ├──
│   ├── index.rst
│   └── requirements.txt
├── README.rst
├── requirements.txt
└── tox.ini

The file ./chemistry_tools/formulae/requirements.txt contains the additional requirements to run the formulae subpackage. These would be defined in like this:

                                "formulae": [

A message can be displayed in the documentation to indicate that the subpackage has these additional requirements that must be installed.

For instance, this:

.. extras-require:: formulae
        :file: formulae/requirements.txt

will produce this:


The path given in :file: is relative to the package_root variable given in, which in turn is relative to the parent directory of the sphinx documentation.

I.e, this line:

package_root = "chemistry_tools"

points to ./chemistry_tools, and therefore :file: formulae/requirements.txt points to ./chemistry_tools/formulae/requirements.txt.

Requirements can also be specified in pyproject.toml (using the option :pyproject:), setup.cfg (using the option :setup.cfg::), or by typing in the requirements manually, one per line.

The :scope: option can be used to specify a different scope for additional requirements, such as package, module, class or function. Any string value can be supplied here.


extras_require can be installed from PyPI or Anaconda.

To install with pip:

$ python -m pip install extras_require

To install with conda:

  • First add the required channels

$ conda config --add channels
$ conda config --add channels
  • Then install

$ conda install extras_require

Enable extras_require by adding “sphinxcontrib.extras_require” to the extensions variable in

extensions = [

For more information see .

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

extras_require-0.5.0.tar.gz (9.9 kB view hashes)

Uploaded source

Built Distribution

extras_require-0.5.0-py3-none-any.whl (35.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page