extras_require

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

Docs
Tests
PyPI
Anaconda
Activity
QA
Other

Overview

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

.
├── chemistry_tools
│   ├── __init__.py
│   ├── formulae
│   │   ├── __init__.py
│   │   ├── compound.py
│   │   ├── formula.py
│   │   ├── parser.py
│   │   └── requirements.txt
│   ├── constants.py
│   └── utils.py
├── doc-source
│   ├── api
│   │   ├── chemistry_tools.rst
│   │   ├── elements.rst
│   │   ├── formulae.rst
│   │   └── pubchem.rst
│   ├── conf.py
│   ├── index.rst
│   └── requirements.txt
├── LICENSE
├── README.rst
├── requirements.txt
├── setup.py
└── tox.ini

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

setup(
                extras_require={
                                "formulae": [
                                                "mathematical>=0.1.7",
                                                "pandas>=1.0.1",
                                                "pyparsing>=2.2.0",
                                                "tabulate>=0.8.3",
                                                "cawdrey>=0.1.2",
                                                "quantities>=0.12.4",
                                                ],
                                }
                )

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 conf.py, 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.

Installation

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 https://conda.anaconda.org/conda-forge
$ conda config --add channels https://conda.anaconda.org/domdfcoding

• Then install

$ conda install extras_require

Enable extras_require by adding "sphinxcontrib.extras_require" to the extensions variable in conf.py:

extensions = [
        ...
        "sphinxcontrib.extras_require",
        ]

For more information see https://www.sphinx-doc.org/en/master/usage/extensions/index.html#third-party-extensions .

Links

• Source: https://github.com/sphinx-toolbox/extras-require
• Bugs: https://github.com/sphinx-toolbox/extras-require/issues