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.

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 .

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 Python 3

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