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.
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:: :file: formulae/requirements.txt :extra: formulae
will look like 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.
Installation
extras_require can be installed with pip:
$ python -m pip install extras_require
Enable extras_require by adding the following line to the extensions variable in conf.py:
"sphinxcontrib.extras_require",
For more information see https://www.sphinx-doc.org/en/master/usage/extensions/index.html#third-party-extensions .
Future Enhancements
Allow use of different “scopes”, e.g. package, module, class, function, depending on what the additional requirements are for.
Support different methods of defining the requirements, e.g. setup.cfg, setup.py, __pkginfo__.py, pyproject.toml, or typing as entries in the directive itself.
Links
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for extras_require-0.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 54e1f84b74ceeaa4e768b9e84d09629980bdcde76ebac4709017a62946b8adfd |
|
MD5 | 4b67002d9afa5df29a2d59b312b46473 |
|
BLAKE2b-256 | f092cd39b9821b50c5d5c55bc992399dcda2bb6f9400f783a70b752f6bfce6ea |