♻️ Make matplotlib dependency optional (#1061)

This commit makes matplotlib (and numpy) optional dependencies, using `pip install sphinx-needs[plotting]`, by:

1. Removing direct uses of numpy
2. Moving the matplotlib import to a function, which can return `None`
3. Handling the `None` case in the `needbar`/`needpie` post-processing, by emmiting a warning and replacing the nodes with error admonitions.

A seperate test job and related test file is added for testing builds with needbar/needpie directives, for when matplotlib is uninstalled.

.github/workflows/ci.yaml

@@ -78,6 +78,30 @@ jobs:
         run: |
           python -m pytest -v --ignore=tests/benchmarks -m "jstest" tests
 
+  tests-no-mpl:
+    name: Test matplotlib uninstalled
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set Up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+      - name: Update pip
+        run: python -m pip install --upgrade pip
+      - name: Install Dependencies
+        run: |
+          python -m pip install -e .[test,docs]
+          python -m pip uninstall -y matplotlib numpy
+          python -m pip freeze
+      - name: Run pytest
+        run: |
+          python -m pytest -v tests/no_mpl_tests.py
+      - name: Run HTML build
+        # the docs should build without matplotlib (just issuing warnings)
+        run: sphinx-build -b html . _build 
+        working-directory: docs
+
   check:
 
     # This job does nothing and is only used for the branch protection
@@ -89,6 +113,7 @@ jobs:
     - lint
     - tests-core
     - tests-js
+    - tests-no-mpl
 
     runs-on: ubuntu-latest
 

README.rst

@@ -61,6 +61,12 @@ Using pip
 
     pip install sphinx-needs
 
+If you wish to also use the plotting features of sphinx-needs (see :ref:`needbar` and :ref:`needpie`), you need to also install ``matplotlib``, which is available *via* the ``plotting`` extra:
+
+.. code-block:: bash
+
+    pip install sphinx-needs[plotting]
+
 .. note::
 
    Prior version **1.0.1** the package was named ``sphinxcontrib-needs``.

docs/conf.py

@@ -49,7 +49,6 @@
     "sphinxcontrib.plantuml",
     "sphinx_needs",
     "sphinx.ext.autodoc",
-    "matplotlib.sphinxext.plot_directive",
     "sphinx_copybutton",
     "sphinxcontrib.programoutput",
     "sphinx_design",

docs/installation.rst

@@ -15,6 +15,12 @@ Using pip
 
     pip install sphinx-needs
 
+If you wish to also use the plotting features of sphinx-needs (see :ref:`needbar` and :ref:`needpie`), you need to also install ``matplotlib``, which is available *via* the ``plotting`` extra:
+
+.. code-block:: bash
+
+    pip install sphinx-needs[plotting]
+
 .. note::
 
    Prior version **1.0.1** the package was named ``sphinxcontrib-needs``.

noxfile.py

@@ -21,6 +21,15 @@ def tests(session, sphinx):
     session.run("pytest", "--ignore", "tests/benchmarks", *posargs, external=True)
 
 
+@session(python=PYTHON_VERSIONS)
+def tests_no_mpl(session):
+    session.install(".[test]")
+    session.run("pip", "uninstall", "-y", "matplotlib", "numpy", silent=True)
+    session.run("echo", "TEST FINAL PACKAGE LIST")
+    session.run("pip", "freeze")
+    session.run("pytest", "tests/no_mpl_tests.py", *session.posargs, external=True)
+
+
 @session(python="3.10")
 def benchmark_time(session):
     session.install(".[test,benchmark,docs]")

pyproject.toml

@@ -34,13 +34,16 @@ packages = [
 [tool.poetry.dependencies]
 python = ">=3.8,<4"
 sphinx = ">=5.0,<8"
-matplotlib = ">=3.3.0"  # needpie
 requests-file = "^1.5.1"  # external links
 requests = "^2.25.1"  # external_links
 jsonschema = ">=3.2.0"  # needsimport schema validation
 sphinx-data-viewer = "^0.1.1"  # needservice debug output
 sphinxcontrib-jquery = "^4"  # needed for datatables in sphinx>=6
 
+# [project.optional-dependencies.plotting]
+# for needpie / needbar
+matplotlib = { version = ">=3.3.0", optional = true }
+
 # [project.optional-dependencies.test]
 pytest = { version = "^7", optional = true }
 lxml = { version = "^4.6.5", optional = true }
@@ -64,10 +67,12 @@ sphinx-design = { version="^0.5", optional = true }
 sphinx-immaterial = { version="0.11.7", optional = true }
 
 [tool.poetry.extras]
-test = ["pytest", "syrupy", "sphinxcontrib-plantuml", "requests-mock", "lxml", "responses", "pytest-xprocess"]
+plotting = ["matplotlib"]
+test = ["matplotlib", "pytest", "syrupy", "sphinxcontrib-plantuml", "requests-mock", "lxml", "responses", "pytest-xprocess"]
 test-parallel = ["pytest-xdist"]
 benchmark = ["pytest-benchmark", "memray"]
 docs = [
+  "matplotlib",
   "sphinxcontrib-plantuml",
   "sphinx-copybutton",
   "sphinxcontrib-programoutput",

sphinx_needs/directives/needbar.py

@@ -1,24 +1,21 @@
+import hashlib
 import math
-import os
 from typing import List, Sequence
 
-import matplotlib
-import numpy
 from docutils import nodes
+from docutils.parsers.rst import directives
 from sphinx.application import Sphinx
 
 from sphinx_needs.config import NeedsSphinxConfig
 from sphinx_needs.data import SphinxNeedsData
 from sphinx_needs.filter_common import FilterBase, filter_needs, prepare_need_list
-from sphinx_needs.utils import add_doc, remove_node_from_tree, save_matplotlib_figure
-
-if not os.environ.get("DISPLAY"):
-    matplotlib.use("Agg")
-import hashlib
-
-from docutils.parsers.rst import directives
-
 from sphinx_needs.logging import get_logger
+from sphinx_needs.utils import (
+    add_doc,
+    import_matplotlib,
+    remove_node_from_tree,
+    save_matplotlib_figure,
+)
 
 logger = get_logger(__name__)
 
@@ -82,7 +79,8 @@ def run(self) -> Sequence[nodes.Node]:
             text_color = text_color.strip()
 
         style = self.options.get("style")
-        style = style.strip() if style else matplotlib.style.use("default")
+        matplotlib = import_matplotlib()
+        style = style.strip() if style else (matplotlib.style.use("default") if matplotlib else "default")
 
         legend = "legend" in self.options
 
@@ -169,8 +167,20 @@ def run(self) -> Sequence[nodes.Node]:
 # 10. cleanup matplotlib
 def process_needbar(app: Sphinx, doctree: nodes.document, fromdocname: str, found_nodes: List[nodes.Element]) -> None:
     env = app.env
+    needs_data = SphinxNeedsData(env)
     needs_config = NeedsSphinxConfig(env.config)
 
+    matplotlib = import_matplotlib()
+
+    if matplotlib is None and found_nodes and needs_config.include_needs:
+        logger.warning(
+            "Matplotlib is not installed and required by needbar. "
+            "Install with `sphinx-needs[plotting]` to use. [needs.mpl]",
+            once=True,
+            type="needs",
+            subtype="mpl",
+        )
+
     # NEEDFLOW
     # for node in doctree.findall(Needbar):
     for node in found_nodes:
@@ -179,7 +189,14 @@ def process_needbar(app: Sphinx, doctree: nodes.document, fromdocname: str, foun
             continue
 
         id = node.attributes["ids"][0]
-        current_needbar = SphinxNeedsData(env).get_or_create_bars()[id]
+        current_needbar = needs_data.get_or_create_bars()[id]
+
+        if matplotlib is None:
+            message = "Matplotlib missing for needbar plot"
+            if current_needbar["title"]:
+                message += f" {current_needbar['title']!r}"
+            node.replace_self(nodes.error("", nodes.paragraph(text=message)))
+            continue
 
         # 1. define constants
         error_id = current_needbar["error_id"]
@@ -253,9 +270,7 @@ def process_needbar(app: Sphinx, doctree: nodes.document, fromdocname: str, foun
 
         # 5. process content
         local_data_number = []
-        need_list = list(
-            prepare_need_list(SphinxNeedsData(env).get_or_create_needs().values())
-        )  # adds parts to need_list
+        need_list = list(prepare_need_list(needs_data.get_or_create_needs().values()))  # adds parts to need_list
 
         for line in local_data:
             line_number = []
@@ -322,7 +337,7 @@ def process_needbar(app: Sphinx, doctree: nodes.document, fromdocname: str, foun
         colors = colors * multi
         colors = colors[: len(local_data)]
 
-        y_offset = numpy.zeros(len(local_data_number[0]))
+        y_offset = [0.0 for _ in range(len(local_data_number[0]))]
 
         # 8. create figure
         bar_labels = []
@@ -347,7 +362,7 @@ def process_needbar(app: Sphinx, doctree: nodes.document, fromdocname: str, foun
 
             if current_needbar["stacked"]:
                 # handle stacked bar
-                y_offset = y_offset + numpy.array(local_data_number[x])
+                y_offset = [i + j for i, j in zip(y_offset, local_data_number[x])]
 
             if current_needbar["show_sum"]:
                 try:
@@ -375,15 +390,14 @@ def process_needbar(app: Sphinx, doctree: nodes.document, fromdocname: str, foun
             if sum_rotation.isdigit():
                 matplotlib.pyplot.setp(bar_labels, rotation=int(sum_rotation))
 
+        centers = [(i + j) / 2.0 for i, j in zip(index[0], index[len(local_data_number) - 1])]
         if not current_needbar["horizontal"]:
             # We want to support even older version of matplotlib, which do not support axes.set_xticks(labels)
-            x_pos = (numpy.array(index[0]) + numpy.array(index[len(local_data_number) - 1])) / 2
-            axes.set_xticks(x_pos)
+            axes.set_xticks(centers)
             axes.set_xticklabels(labels=xlabels)
         else:
             # We want to support even older version of matplotlib, which do not support axes.set_yticks(labels)
-            y_pos = (numpy.array(index[0]) + numpy.array(index[len(local_data_number) - 1])) / 2
-            axes.set_yticks(y_pos)
+            axes.set_yticks(centers)
             axes.set_yticklabels(labels=xlabels)
             axes.invert_yaxis()  # labels read top-to-bottom