Use pytest-doctestplus instead of classic pytest-doctest (#7289)

* Use pytest-doctestplus
Lets us hide custom test setup from the rendered HTML docstrings;
many more perks we be useful in the future.

doctestplus has its own mechanism of skipping doctests if dependencies
are not required. However, it seems that using `__doctest_skip__` will
not show that tests were skipped, so instead used an approach
based on `.. testsetup` and `pytest.importorskip`.

* Add pytest-doctestplus to doc dependencies
(needed to parse the .. testsetup fixture)

CONTRIBUTING.rst

@@ -264,7 +264,7 @@ Run:
 - Run tests with **arbitrary ``pytest`` options**:
   ``spin test -- any pytest args you want``.
 - Run all tests and **doctests**:
-  ``spin test -- --doctest-modules skimage``
+  ``spin test -- --doctest-plus skimage``
 
 Warnings during testing phase
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

azure-pipelines.yml

@@ -168,7 +168,7 @@ jobs:
           export MATPLOTLIBRC=${AGENT_BUILDDIRECTORY}
 
           # Run unit tests with pytest
-          # We don't test docstring examples (--doctest-modules) on
+          # We don't test docstring examples (--doctest-plus) on
           # Windows due to inconsistent ndarray formatting in `numpy`.
           # For more details, see https://github.com/numpy/numpy/issues/13468
           export TEST_ARGS="-v --cov=skimage"

doc/source/conf.py

@@ -55,6 +55,7 @@
     "sphinx_design",
     "matplotlib.sphinxext.plot_directive",
     "myst_parser",
+    "pytest_doctestplus.sphinx.doctestplus",
     "skimage_extensions",
 ]
 

pyproject.toml

@@ -84,6 +84,7 @@ docs = [
     'sphinx_design>=0.5',
     'pydata-sphinx-theme>=0.15.1',
     'PyWavelets>=1.1.1',
+    'pytest-doctestplus',
 ]
 optional = [
     'SimpleITK',
@@ -105,6 +106,7 @@ test = [
     'pytest-cov>=2.11.0',
     'pytest-localserver',
     'pytest-faulthandler',
+    'pytest-doctestplus',
 ]
 
 [project.urls]

requirements/docs.txt

@@ -20,3 +20,4 @@ scikit-learn>=1.1
 sphinx_design>=0.5
 pydata-sphinx-theme>=0.15.1
 PyWavelets>=1.1.1
+pytest-doctestplus

requirements/test.txt

@@ -8,3 +8,4 @@ pytest>=7.0
 pytest-cov>=2.11.0
 pytest-localserver
 pytest-faulthandler
+pytest-doctestplus

skimage/feature/_fisher_vector.py

@@ -79,8 +79,9 @@ def learn_gmm(descriptors, *, n_modes=32, gm_args=None):
 
     Examples
     --------
-    >>> import pytest
-    >>> _ = pytest.importorskip('sklearn')
+    .. testsetup::
+        >>> import pytest; _ = pytest.importorskip('sklearn')
+
     >>> from skimage.feature import fisher_vector
     >>> rng = np.random.Generator(np.random.PCG64())
     >>> sift_for_images = [rng.standard_normal((10, 128)) for _ in range(10)]
@@ -191,8 +192,9 @@ def fisher_vector(descriptors, gmm, *, improved=False, alpha=0.5):
 
     Examples
     --------
-    >>> import pytest
-    >>> _ = pytest.importorskip('sklearn')
+    .. testsetup::
+        >>> import pytest; _ = pytest.importorskip('sklearn')
+
     >>> from skimage.feature import fisher_vector, learn_gmm
     >>> sift_for_images = [np.random.random((10, 128)) for _ in range(10)]
     >>> num_modes = 16

skimage/restoration/_denoise.py

@@ -959,8 +959,9 @@ def denoise_wavelet(
 
     Examples
     --------
-    >>> import pytest
-    >>> _ = pytest.importorskip('pywt')
+    .. testsetup::
+        >>> import pytest; _ = pytest.importorskip('pywt')
+
     >>> from skimage import color, data
     >>> img = img_as_float(data.astronaut())
     >>> img = color.rgb2gray(img)
@@ -1084,8 +1085,9 @@ def estimate_sigma(image, average_sigmas=False, *, channel_axis=None):
 
     Examples
     --------
-    >>> import pytest
-    >>> _ = pytest.importorskip('pywt')
+    .. testsetup::
+        >>> import pytest; _ = pytest.importorskip('pywt')
+
     >>> import skimage.data
     >>> from skimage import img_as_float
     >>> img = img_as_float(skimage.data.camera())

tools/github/script.sh

@@ -7,7 +7,7 @@ export MPL_DIR=`python -c 'import matplotlib; print(matplotlib.get_configdir())'
 mkdir -p $MPL_DIR
 touch $MPL_DIR/matplotlibrc
 
-TEST_ARGS="--doctest-modules --cov=skimage --showlocals"
+TEST_ARGS="--doctest-plus --cov=skimage --showlocals"
 
 if [[ ${WITHOUT_POOCH} == "1" ]]; then
   # remove pooch (previously installed via requirements/test.txt)