Repository navigation
Add a related examples section to all gallery entries #19230
Description
Problem
For the most part I (and I assume most people) end up at any given example in the gallery through some combination of googling somewhat incoherent phrases and links out from stackoverflow. This actually works great due to the breadth of topics covered in the examples. However there is no natural path for a reader to discover related examples.
e.g. If I end up on https://matplotlib.org/devdocs/gallery/statistics/histogram_features.html#sphx-glr-gallery-statistics-histogram-features-py
then there is no easy way to find the other histogram examples, or even to know that others exist. This is a shame as there are many other histogram examples:
This is especially so because of however the examples get placed into the toctree the next level up from the example page is the contents page rather than the list of examples:
I think that at least part of #19221 is a special case of this general issue.
Suggested Improvement
Implement a standard section in all examples for Related Examples or Further Reading or something to that effect. Then slowly implement this over all the examples and require it in all future examples.
This could be done already, but it would be very nice to have a standard set for how to do this.
Activity
jklymak commentedon Jan 4, 2021
If you click through to https://matplotlib.org/devdocs/api/_as_gen/matplotlib.axes.Axes.hist.html#matplotlib.axes.Axes.hist there is a list of many examples that include hist at the bottom of the page. This to me is the right place to have the list. I suppose it is conceivable that this info could be replicated at the bottom of each of those examples - I'm not sure if there are performance penalties this could incur, and I'm not sure any such capability exists in sphinx gallery.
ianhi commentedon Jan 4, 2021
That list is indeed nice, that said I've rarely, if ever, scrolled down to it, and that's pretty difficult to end up at directly from an example. A nice improvement could even be to directly link to that list from the examples where it seems relevant.
An issue with that list though it that the examples included in are not included in the meta-topic
Learning basic histogram techniquesI think I was envisioning. For example all of these:are great examples, and I think stand on their own, but aren't really
related examplesto a basic histogram example. More generally here are their any guidelines for what should be included in the references section of the example? Should every example referenceplt.subplots? or is their some strategy for being parsimonious with referencing oft used functions?timhoffm commentedon Jan 4, 2021
Related examples could be nice.
We sometimes link other examples from the description, see e.g.
The references section is currently only intended for function/class references. It's main purpose is to add code that will add the example to the mini-gallery under the referenced function/class. But we might change that; see #19232.
I have some concerns that a broad introduction of cross-links won't work because curating these is a lot of additional manual work. We don't even get close to having the function/class references documented properly. And there's some redundancy in the examples which would be good to get cleaned out. So there is already a lot of open work in that area. OTOH it may be useful to specify a pattern for cross-linking examples (possibly as part of the References sectio, xref #19232). And if we have such links it may help cleaning redundancy later.
ianhi commentedon Jan 4, 2021
It seems to me that even a sparse cross linking of examples would purely be an improvement. Having a pattern to specify this (especially one that embeds the thumbnail as well) would be great.
As I've been perusing the examples more carefully I've also been thinking this. But was hesitant to suggest since removal of resources does not seem ideal. Though I suppose clutter can make it more confusing.
jklymak commentedon Jan 4, 2021
I try and cross link new examples and try to ask new examples do so. Someone could go through and add more such cross links, but I'm skeptical about automagically adding a whole bunch.
As always the issue with removing and reorganizing examples is redirecting old locations. Someone noted that there may be a new Sphinx extension to set up redirects.
github-actions commentedon Sep 25, 2023
This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!
rcomer commentedon Sep 25, 2023
I guess this could be addressed by @esibinga's tagging work?
melissawm commentedon Oct 9, 2023
@rcomer that is the plan, but I'd suggest keeping this open in case we need extra features to group examples later.