Make plot detection in docstrings more flexible

[florian-wagner]

I was wondering why some of my docstring examples are not rendered, until I found that import matplotlib.pyplot as plt works, while from matplotlib import pyplot as plt does not, since numpydoc explicitly checks if a string contains import matplotlib.

Aside from import conventions, it would be desirable to have a more flexible plot detection, since a lot of projects have high-level wrappers around matplotlib. For example, our project has a "show" function, which plots simulation results on arbitrary finite element meshes (and imports mpl internally).

[stefanv]

@florian-wagner Since we operate on strings only, I'm not sure how to implement this suggestion. Do you have any ideas?

[florian-wagner]

@stefanv I was hoping it is possible to detect figures created by a an example docstring, rather than looking for the mpl import explicitly. Maybe something similar to this: https://github.com/sphinx-gallery/sphinx-gallery/blob/master/sphinx_gallery/gen_rst.py#L326-L341

[stefanv]

@florian-wagner It looks, from the example that you linked, that they have hooks while executing the code, which Sphinx does not do.

[florian-wagner]

@stefanv Okay I see, maybe a simple and flexible solution would be to allow user-specification of the string (or better list of strings) that numpydoc searches for to identify examples with plots, i.e. optionally setting something like

plot_commands = ["import matplotlib", "from matplotlib import pyplot as plt", "mypackage.plot2D"]

in your conf.py. Do you think that's possible?

[stefanv]

That seems doable, yes.

[jnothman]

As of #125 (27960ff), we now support from matplotlib import. I'm closing. Reopen if that's not sufficient.

[jnothman]

We could offer a config param for more flexibility if sought. At the moment we have fixed IMPORT_MATPLOTLIB_RE = r'\b(import +matplotlib|from +matplotlib +import)\b'

[mdeff]

I have the same issue as @florian-wagner, i.e., a library (PyGSP) that wraps matplotlib for its own plotting functions. It would be great to be able to configure the detection, something like the plot_commands config param proposed above. @jnothman would that be reasonable to implement?

[jnothman]

I don't see why not... But warning that numpydoc gets maintained quite slowly.