Should examples in docstrings be included in the example gallery? #378
Description
This is a new issue for a philosophical discussion about whether or not the new Example Gallery should include examples harvested from docstrings. It started in astropy/sphinx-astropy#22 with @bsipocz and @jonathansick.
I think it's absolutely fine for this functionality to exist, however, I'm not convinced it's a great idea for us to implement. A big goal of our example gallery is to bring people into the documentation. The examples in the gallery will link back to the place where they were harvested from. It's my understanding, that the docstrings are in a place in the docs where there's not a lot of explanation. At this point, I would prefer we actually duplicate the examples in the docstrings somewhere in the more wordy part of the docs.
But this is just my current thinking, I'm not sure of the best way to go. @bsipocz , maybe you can link to some of the examples you're thinking would be good for the gallery?