Directive

.. extras-require::

The requirements can be specified in several ways:

:file: requirements_file (string)

Shows the requirements from the given file. The file must contain a list of PEP 508 requirements, one per line.

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

:__pkginfo__: (flag)

Flag to indicate the requirements should be obtained from __pkginfo__.py.

This looks in the parent directory of the sphinx documentation for a file named __pkginfo__.py. The requirements are imported as the variable extras_require, which must be a dictionary mapping extras to a list of requirements.

Example:

extras_require = {
        "extra_b": [
                "flask>=1.1.2",
                "click<7.1.2",
                "sphinx==3.0.3",
                ],
        }

The requirements can be generated programmatically in the __pkginfo__.py file during the import process.

:setup.cfg: (flag)

Flag to indicate the requirements should be obtained from setup.cfg.

This looks in the parent directory of the sphinx documentation for a file named setup.cfg. This file must be readable by Python’s configparser module, and contain the section [options.extras_require].

Example:

[options.extras_require]
extra_c = faker; pytest; tox

See the setuptools documentation for more information on setup.cfg.

:flit: (flag)

Flag to indicate the requirements should be obtained from the [tool.flit.metadata.requires-extra] section of pyproject.toml.

Example:

[tool.flit.metadata.requires-extra]
test = [
    "pytest>=2.7.3",
    "pytest-cov",
]
doc = ["sphinx"]

See the flit documentation for more details.

:pyproject: (flag)

Flag to indicate the requirements should be obtained from the [project.optional-dependencies] section of pyproject.toml.

Example:

[project.optional-dependencies]
test = [
  "pytest<5.0.0",
  "pytest-cov[all]"
]

See the PEP 621 section on dependencies/optional-dependencies for more details.

Only one of the above options can be used in each directive.

Manual requirements:

If none of the above options are provided the PEP 508 requirements can instead be provided as the content of the directive. Each requirement must be on its own line, and there must be a blank line between the directive and the list of requirements. e.g.

.. extras-require:: dates

    pytz >=2019.1

Attention

This module has the following additional requirement:

pytz>=2019.1

This can be installed as follows:

python -m pip install chemistry_tools[dates]

Other options:

:scope: (string)

Specifies a different scope for additional requirements, such as package, module, class or function.

Any string value can be supplied here.

Example

.. extras-require:: foo
    :scope: class

    bar
    baz

Attention

This class has the following additional requirements:

bar
baz

These can be installed as follows:

python -m pip install chemistry_tools[foo]