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 |
|
---|---|
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
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.4.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6d51966729a2d599e8a7ae3d53bd04a02d984464e7ed24de3988d7706ef6a1d5 |
|
MD5 | 1e8226f594d8218bc422f95359424d0c |
|
BLAKE2b-256 | b4c54ef62f686cf4a60fd701a3d56a0c568c034e2706df0152c84f20c63532bd |