Document that the matplotlib backend will be set to Agg

[anntzer]

While trying to use sphinx-gallery to document my mplcursors (https://mplcursors.readthedocs.io/en/stable/) package, I got the following (well-known) warning:

UserWarning:  This call to matplotlib.use() has no effect
because the backend has already been chosen;
matplotlib.use() must be called *before* pylab, matplotlib.pyplot,
or matplotlib.backends is imported for the first time.

Turns out that in my conf.py, I already import mplcursors/__init__.py (in order to get the version set by versioneer out of it), and that this triggers an import of matplotlib.pyplot (which I can actually get rid of, but that's irrelevant here). A simple solution was simply to set the backend to Agg before importing mplcursors.

Documenting this point could perhaps save some head-scratching for others too.

[lesteve]

Makes sense. I am wondering whether it would not be possible to raise an error inside sphinx-gallery if the matplotlib backend has already been set to something else that Agg.

[anntzer]

Given that switching backends is rather poorly supported by matplotlib, that probably makes sense.

[Titan-C]

Makes sense. I am wondering whether it would not be possible to raise an error inside sphinx-gallery if the matplotlib backend has already been set to something else that Agg.

I prepared PR #157. It will issue a warning instead of raising an error.

[anntzer]

btw, matplotlib/matplotlib#7303 was merged into matplotlib recently, so that may or may not be enough by itself.