Skip to content

sphinx-toolbox/extras_require

Repository files navigation

extras_require

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

Docs Documentation Build Status Docs Check Status
Tests Linux Test Status Windows Test Status macOS Test Status Coverage
PyPI PyPI - Package Version PyPI - Supported Python Versions PyPI - Supported Implementations PyPI - Wheel
Anaconda Conda - Package Version Conda - Platform
Activity GitHub last commit GitHub commits since tagged version Maintenance PyPI - Downloads
QA CodeFactor Grade Flake8 Status mypy status
Other License GitHub top language Requirements Status

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:

doc-source/example.png

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