Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

♻️ Make matplotlib dependency optional #1061

Merged
merged 3 commits into from
Nov 8, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions .github/workflows/ci.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -89,6 +113,7 @@ jobs:
- lint
- tests-core
- tests-js
- tests-no-mpl

runs-on: ubuntu-latest

Expand Down
6 changes: 6 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.
Expand Down
1 change: 0 additions & 1 deletion docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,6 @@
"sphinxcontrib.plantuml",
"sphinx_needs",
"sphinx.ext.autodoc",
"matplotlib.sphinxext.plot_directive",
"sphinx_copybutton",
"sphinxcontrib.programoutput",
"sphinx_design",
Expand Down
6 changes: 6 additions & 0 deletions docs/installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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``.
Expand Down
9 changes: 9 additions & 0 deletions noxfile.py
Original file line number Diff line number Diff line change
Expand Up @@ -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]")
Expand Down
33 changes: 17 additions & 16 deletions poetry.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

9 changes: 7 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
Expand All @@ -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",
Expand Down
58 changes: 36 additions & 22 deletions sphinx_needs/directives/needbar.py
Original file line number Diff line number Diff line change
@@ -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__)

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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:
Expand All @@ -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"]
Expand Down Expand Up @@ -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 = []
Expand Down Expand Up @@ -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 = []
Expand All @@ -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:
Expand Down Expand Up @@ -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

Expand Down
Loading