Retire the examples/ folder?

[bmcfee]

It occurs to me that the examples/ folder isn't serving much of a purpose anymore, and we may do better to retire it. I certainly don't want to maintain it if it's never used.

The example scripts are not packaged in the distribution, nor are they referred to in the documentation.

$ ls -1
adjust_tuning.py*
beat_tracker.py*
estimate_tuning.py*
hpss_beats.py*
hpss.py*
'LibROSA audio effects and playback.ipynb'
'LibROSA demo.ipynb'
onset_detector.py*
time_stretch.py*

I think almost all of these cases are better covered at this point by either the specific docstring examples (eg onset detector, beat tracker, or time stretch) or the advanced examples in the gallery (audio effects, demo notebook).

I'd be open to expanding to the advanced example gallery to cover anything crucial that we'd lose by removing the examples folder. What do the other devs think?

[lostanlen]

Yes, this is a good idea.
But in return, it would be good to give more visibility to the gallery. At the moment (unless i'm mistaken) the gallery appears neither in the README neither in the home page of librosa.org

[bmcfee]

But in return, it would be good to give more visibility to the gallery. At the moment (unless i'm mistaken) the gallery appears neither in the README neither in the home page of librosa.org

Yeah, we can do both of those for the upcoming release.

Back on examples/: the one place it does pop up is in the caching section of the docs.

[underdogliu]

As a junior-level end user I think jupyter notebooks is still a good idea for demonstrations. If it sounds valid, there are two options:

• Change all tutorials to jupyter notebooks and store files relevant online;
• Use Google Colab. Files are treated in the same way.

A re-naming from examples to tutorials or notebooks may also make more sense?

[bmcfee]

Thanks for your input here. I don't want to tie us to colab, given google's propensity to discontinue useful services, but it's easy enough to add examples in the gallery. These can automatically export to notebooks, which ought to be good enough.

[bmcfee]

I just took a skim through these old demos, and I don't think there's anything in here that isn't covered better by the docstring examples and gallery. This isn't to say that the current gallery couldn't be expanded with more basic, end-to-end examples, but I don't think we lose much by purging examples/ and starting fresh.

[lostanlen]

at the risk of sounding contrarian: the librosa gallery does not explain playback ...

import librosa
from IPython.display import Audio

sr = 22050
y = librosa.tone(frequency=440, sr=sr, duration=1.0)
Audio(data=y, rate=sr)

[bmcfee]

Fair enough. I've avoided it previously because embedded audio widgets are sketchy territory when it comes to sphinx-gallery. Maybe it works fine though?

[lostanlen]

Another possible venue is ... https://librosa.org/blog/ 😋

[bmcfee]

Aha! Audio embeds do work, but the only catch is that you can't stack them using display like in a notebook. I can work around that easily enough.