Make matplotlib a optional requirement

[JakobDev]

This makes it easier to install. Currently matplotlib is nowhere mentioned, so you only know that you need it by reading the Sphinx Log.

[polyzen]

https://github.com/wpilibsuite/sphinxext-opengraph/pull/104 already merged

[JakobDev]

The PR your linked is different. It removes matplotlib completely from the requirements. But this PR adds it as optional requirement.

[Daltz333]

I'm not sure what's standard in the Python world here. I don't see a lot of projects actually using pip's support for optional requirements.

[JakobDev]

Maybe many People don't know that they exists. There are also not many Projects which have optional requirements. It's at least better than the current situation.

[hugovk]

Looking at https://github.com/sethmlarson/pypi-data ("Mostly up-to-date data about almost every package on PyPI"), 42,168 out of 224,410 have extra requirements (requires_extras), or 19%.

❯ sqlite3 'pypi.db' 'SELECT package_name, extra FROM deps GROUP BY package_name;' | wc -l
  224410

❯ sqlite3 'pypi.db' 'SELECT package_name, extra FROM deps WHERE extra IS NOT NULL GROUP BY package_name;' | wc -l
   42168

[kloczek]

BTW optional matplotlib dependency. I have at the moment few packaged python modules which documentation builds depends on sphinxext-opengraph

[tkloczko@pers-jacek SPECS]$ grep 'BuildRequires:.*python3dist(sphinxext-opengraph)' -l *spec
python-argcomplete.spec
python-jsonschema-specifications.spec
python-jsonschema.spec
python-meson-python.spec
python-myst-parser.spec
python-pillow.spec
python-pyotp.spec
python-referencing.spec
python-sphinx-book-theme.spec
python-sphinx-json-schema-spec.spec
python-sphinx-sitemap.spec
python-sphinxext-opengraph.spec
python-structlog.spec
python-urllib3.spec
python-webcolors.spec
python-websockets.spec
python-xarray.spec
srain.spec

Just checked my build logs and

[tkloczko@pers-jacek SPECS]$ xzgrep -l "cannot import name 'pyplot' from 'matplotlib'" *xz
python-argcomplete.FAIL.xz
python-jsonschema-specifications.FAIL.xz
python-meson-python.FAIL.xz
python-pillow.FAIL.xz
python-pyotp.FAIL.xz
python-structlog.FAIL.xz
python-webcolors.FAIL.xz
python-websockets.FAIL.xz

IMO matplotlib dependency should not be as an optional because it causes more harm than good.

Here is example from building webcolors documenation:

+ /usr/bin/sphinx-build -n -T -b man docs build/sphinx/man
Running Sphinx v7.2.6

Traceback (most recent call last):
  File "/usr/lib/python3.10/site-packages/sphinx/registry.py", line 447, in load_extension
    mod = import_module(extname)
  File "/usr/lib64/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/usr/lib/python3.10/site-packages/sphinxext/opengraph/__init__.py", line 19, in <module>
    from .socialcards import create_social_card, DEFAULT_SOCIAL_CONFIG
  File "/usr/lib/python3.10/site-packages/sphinxext/opengraph/socialcards.py", line 5, in <module>
    from matplotlib import pyplot as plt
ImportError: cannot import name 'pyplot' from 'matplotlib' (unknown location)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/usr/lib/python3.10/site-packages/sphinx/cmd/build.py", line 293, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/usr/lib/python3.10/site-packages/sphinx/application.py", line 233, in __init__
    self.setup_extension(extension)
  File "/usr/lib/python3.10/site-packages/sphinx/application.py", line 406, in setup_extension
    self.registry.load_extension(self, extname)
  File "/usr/lib/python3.10/site-packages/sphinx/registry.py", line 450, in load_extension
    raise ExtensionError(__('Could not import extension %s') % extname,
sphinx.errors.ExtensionError: Could not import extension sphinxext.opengraph (exception: cannot import name 'pyplot' from 'matplotlib' (unknown location))

Extension error:
Could not import extension sphinxext.opengraph (exception: cannot import name 'pyplot' from 'matplotlib' (unknown location))

I'm going to add in my sphinxext-opengraph packaging procedure patch to move from extras_require to install_requires.

[kloczek]

Update: when I've been checking build logs in build queue where still few packages with sphinxext-opengraph build dependency. Now that failing list exceeds more than half of all packages which are using sphinxext-opengraph python module.