Repository: librosa/librosa

Issue:
Update historical documentation builds
Note: this should be among the last issues implemented in 0.10 because of how our doc build CI works.

When we release 0.10, we should drop the historical build of 0.7.2 and only keep the latest releases from the 0.8 and 0.9 series. (0.8.1, 0.9.2).

Dropping the 0.7 series from doc builds should allow us to update the documentation environment dependencies, specifically for numba, matplotlib, and numpy.

Our doc build uses numba 0.48 because 0.7.2 predates #1164 (0.8.0) to use the newer API.  Removing the 0.7 build should relax this constraint.

#1393 notes the issue with numpy versions - dropping 0.7 allows us to move up to numpy > 1.17 if we want.  This could allow us to go into mypy / typing (numpy >= 1.20) for example.

Likewise, #1324 (0.8.1) supports matplotlib>=3.5, so we no longer have to build on 3.3.  Supporting 3.5 in the doc build removes a potential conflict with some new features slated for 0.10, eg #1426 #1422 #929.  That said, this does present a race condition for merging those features vs. maintaining historical doc builds until the 0.10 release.  I'm not sure how best to handle that yet - maybe we just have to drop 0.7 docs before the release?




Discussion:
Implementing #1480 will also require bumping the numba version (to one which does not yet exist) - so we'll need to resolve this issue first to avoid environment conflicts in our doc builds.

I think this settles that we'll need to remove the 0.7 build well in advance of the 0.10 release.  I'm not sure how much of an issue this is; according to https://libraries.io/pypi/librosa/usage , we have about 18% of dependent repositories using 0.7 series, but i expect most of those are stale.  Google analytics is down for me right now, so I can't comment directly on site traffic to the historical doc build.
Ok, google analytics is back up - looks like we get about 4% traffic to the 0.7.2 site, the rest splits between `main` (dev) and `latest` (stable) over the past week:
![image](https://user-images.githubusercontent.com/1190540/175994404-a8427615-ec5a-41ea-9361-c5545fee9eb9.png)
and for YTD (2022) we have about the same:
![image](https://user-images.githubusercontent.com/1190540/175994731-21a64d7c-97cb-44ab-a0de-a758f91f2fbc.png)

It also turns out that the wayback machine tracks our doc site, so even if we drop the 0.7 build, it won't be gone forever.  Since we're talking about 4% of our traffic at this point, I feel okay with dropping 0.7 builds in support of ongoing development.
It looks like our doc build is now broken due to dependency conflicts.  It might be time to start on this issue then.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -380,7 +380,7 @@ def reset_mpl(gallery_conf, fname):
 autodoc_member_order = "bysource"
 
 smv_branch_whitelist = r"^main$"  # build main branch, and anything relating to documentation
-smv_tag_whitelist = r"^((0\.7\.2)|(0\.8\.1)|(0\.[9]\.\d+))$"  # use this for final builds
+smv_tag_whitelist = r"^((0\.8\.1)|(0\.[9]\.\d+))$"  # use this for final builds
 smv_released_pattern = r'.*tags.*'
 smv_remote_whitelist = r'^origin$'
 smv_prefer_remote_refs = True
diff --git a/librosa/version.py b/librosa/version.py
--- a/librosa/version.py
+++ b/librosa/version.py
@@ -57,7 +57,6 @@ def show_versions():
         "matplotlib",
         "samplerate",
         "soxr",
-        "contextlib2",
         "presets",
     ]
 


Test patch:
diff --git a/tests/test_beat.py b/tests/test_beat.py
--- a/tests/test_beat.py
+++ b/tests/test_beat.py
@@ -2,8 +2,6 @@
 # CREATED:2013-03-11 18:14:30 by Brian McFee <brm2132@columbia.edu>
 #  unit tests for librosa.beat
 
-from __future__ import print_function
-
 # Disable cache
 import os
 
@@ -13,7 +11,7 @@
     pass
 
 import pytest
-from contextlib2 import nullcontext as dnr
+from contextlib import nullcontext as dnr
 
 import numpy as np
 import scipy.stats
diff --git a/tests/test_effects.py b/tests/test_effects.py
--- a/tests/test_effects.py
+++ b/tests/test_effects.py
@@ -11,7 +11,7 @@
 except KeyError:
     pass
 
-from contextlib2 import nullcontext as dnr
+from contextlib import nullcontext as dnr
 import numpy as np
 import pytest
 
diff --git a/tests/test_filters.py b/tests/test_filters.py
--- a/tests/test_filters.py
+++ b/tests/test_filters.py
@@ -19,7 +19,7 @@
 except KeyError:
     pass
 
-from contextlib2 import nullcontext as dnr
+from contextlib import nullcontext as dnr
 import glob
 import numpy as np
 import scipy.io
diff --git a/tests/test_multichannel.py b/tests/test_multichannel.py
--- a/tests/test_multichannel.py
+++ b/tests/test_multichannel.py
@@ -3,8 +3,6 @@
 #  unit tests for multi-channel functionality
 #
 
-from __future__ import print_function
-
 # Disable cache
 import os
 
@@ -21,7 +19,7 @@
 import warnings
 from unittest import mock
 
-from contextlib2 import nullcontext as dnr
+from contextlib import nullcontext as dnr
 from test_core import srand
 
 
diff --git a/tests/test_onset.py b/tests/test_onset.py
--- a/tests/test_onset.py
+++ b/tests/test_onset.py
@@ -2,9 +2,8 @@
 # CREATED:2013-03-11 18:14:30 by Brian McFee <brm2132@columbia.edu>
 #  unit tests for librosa.onset
 
-from __future__ import print_function
 import pytest
-from contextlib2 import nullcontext as dnr
+from contextlib import nullcontext as dnr
 
 # Disable cache
 import os