Repository navigation
Refactor legend documentation #9458
Description
@anntzer recently pointed out that we've got a lot of documentation on legends scattered throughout the website. Some has higher quality than others, some has mixed levels of user expertise, some are in unintuitive places. I'm putting a list that @anntzer collected below in case somebody wants to take a stab.
Tutorial:
- Legend guide: http://matplotlib.org/tutorials/intermediate/legend_guide.html#sphx-glr-tutorials-intermediate-legend-guide-py
quite advanced, probably can use some rewriting but OK.
Examples:
- Legend demo: http://matplotlib.org/gallery/text_labels_and_annotations/legend_demo.html#sphx-glr-gallery-text-labels-and-annotations-legend-demo-py
Looks somewhere between what this PR proposes and the legend guide. I think this PR is a nice piece of work but I would suggest trying not to spread the same information too thinly across many examples; perhaps the three "narrative" legend examples/tutorials could be merged into two? - What's new in 0.98.4 legend: http://matplotlib.org/gallery/pyplots/whats_new_98_4_legend.html#sphx-glr-gallery-pyplots-whats-new-98-4-legend-py
Can probably be deleted and the relevant features split across other examples. - Polar legend: http://matplotlib.org/gallery/pie_and_polar_charts/polar_legend.html#sphx-glr-gallery-pie-and-polar-charts-polar-legend-py
Can probably deleted, there's nothing special about legends in polar plots. - Simple legend 1 and 2: http://matplotlib.org/gallery/userdemo/simple_legend01.html#sphx-glr-gallery-userdemo-simple-legend01-py http://matplotlib.org/gallery/userdemo/simple_legend02.html#sphx-glr-gallery-userdemo-simple-legend02-py
Should probably be unified. - Legend picking: http://matplotlib.org/gallery/event_handling/legend_picking.html#sphx-glr-gallery-event-handling-legend-picking-py
Is really about event handling so can stand by itself. - Figure legend: http://matplotlib.org/gallery/text_labels_and_annotations/figlegend_demo.html#sphx-glr-gallery-text-labels-and-annotations-figlegend-demo-py
Should probably be rewritten to use a single legend for the whole figure... - Transparent, fancy legends: http://matplotlib.org/gallery/recipes/transparent_legends.html#sphx-glr-gallery-recipes-transparent-legends-py
Is basically the default now... probably doesn't need to exist by itself. - Scatter legend: http://matplotlib.org/gallery/lines_bars_and_markers/scatter_with_legend.html#sphx-glr-gallery-lines-bars-and-markers-scatter-with-legend-py
Heh, why not. - Legend using predefined labels: http://matplotlib.org/gallery/api/legend.html#sphx-glr-gallery-api-legend-py
- and the change in custom legends example #9451
Suggestions:
- Add relevant documentation to address legend handle size does not automatically scale with linewidth #8789 (i.e. the improper scaling of the legend handles with default values for the legend parameters)
Activity
jklymak commentedon Oct 17, 2017
Someone (@NelleV?) mentioned a meta-plan @tacaswell had for the docs. Is that available somewhere? Not much point in reorganizing this if there is a more general re-organization in the works in the near future.
Looking at the Tutorials section, I think its not too bad, but I wonder if some of the divisions are artificial. i.e. "introductory" versus "intermediate" etc. One could imagine a different outline based on subject, where each subject went from introductory to advanced. i.e. in this context you could imagine it being part of a section:
choldgraf commentedon Oct 17, 2017
yep, there is such a meta-plan. I'm putting this issue here so that the general ideas don't get lost, but I agree that the more general documentation refactoring is where this could/should happen
afvincent commentedon Oct 18, 2017
@choldgraf I hope you don't mind: I added another bullet point to your initial post (well actually I added a whole new section, with a single bullet point at the moment ^^)
choldgraf commentedon Oct 18, 2017
github-actions commentedon Apr 21, 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!