Daniel McCloy

Circle failure is this: ``` /home/circleci/python_env/lib/python3.10/site-packages/sphinx_gallery/scrapers.py:171: UserWarning: This figure includes Axes that are not compatible with tight_layout, so results might be incorrect. fig.savefig(image_path, **these_kwargs) ```

> several base classes which I believe never actually become relevant to users The base classes are public precisely because I (as an end user) needed to use them in...

That would have worked too (and, in retrospect, would have avoided the documentation issue you're confused by). Something like that approach (creating a new convenience construct `epochs_types`) was also proposed...

> But this was decided 6 years ago. Today, type hints & checking are finding more and more widespread use. yep. > We should therefore revisit this decision sometime in...

https://github.com/mne-tools/mne-python/blob/fefa7dba887089a46cf5e0f8836ff6fb07be2552/tutorials/epochs/10_epochs_overview.py#L421-L426

to me this feels like something that should be fixed upstream. Maybe IPython should suppress displaying the output of cells if that output is a matplotlib `Figure` instance. Or maybe...

> So in my opinion the problem is that plotting functions should not return a `Figure`, but some `axis` subtype or line collection or similar. what our plotting functions *should*...

> if all our plotting functions return e.g. axis, they are also consistent. we cannot achieve that though. Many of our plotting functions generate complex figures with many subplots. Which...

> seaborn has functions that plot more complex figures (with multiple axes) that still do not return a figure, but do it through some container types. Good point. Still, I...

@cbrnr you can test if it works by adding a repr_html here: https://github.com/mne-tools/mne-python/blob/main/mne/viz/_mpl_figure.py#L83 and trying raw.plot() in a notebook after that.