Repository navigation
DOC: Add more explanatory comments to gallery examples #11654
Description
@erinleeryan raised the concern that many of the matplotlib gallery examples have very little to no prose documentation, which can be frustrating for users unfamiliar with matplotlib conventions.
For example, in the stem plot example below it is unclear what markerline, stemlines, and baseline are relative the plot, and why plt.stem returns those three objects and what the plt.setp function is doing.
import matplotlib.pyplot as plt
import numpy as np
x = np.linspace(0.1, 2 * np.pi, 10)
markerline, stemlines, baseline = plt.stem(x, np.cos(x), '-.')
plt.setp(baseline, color='r', linewidth=2)
plt.show()As suggested by @erinleeryan, it would be a welcome improvement to the docs to add short one line comments explaining what each line is doing, as shown in the pie chart example below:
# Pie chart, where the slices will be ordered and plotted counter-clockwise:
labels = 'Frogs', 'Hogs', 'Dogs', 'Logs'
sizes = [15, 30, 45, 10]
explode = (0, 0.1, 0, 0) # only "explode" the 2nd slice (i.e. 'Hogs')
fig1, ax1 = plt.subplots()
ax1.pie(sizes, explode=explode, labels=labels, autopct='%1.1f%%',
shadow=True, startangle=90)
ax1.axis('equal') # Equal aspect ratio ensures that pie is drawn as a circle.
plt.show()As an aside, we probably should also remove "simple" and "basic" from the titles of examples, as the gallery image will indicate the level of complexity of the example to the user.
Activity
gabru-md commentedon Jul 15, 2018
Hello @story645,
I would like to work on this issue. I can write the comments for the example files incase no one else is working on it. 🐱
story645 commentedon Jul 17, 2018
Go for it! This issue is fairly broad, so supports multiple people working on it.
timhoffm commentedon Jul 17, 2018
I think we should establish some guidelines what should be in examples and what not. Some rules that come to my mind (not necessarily polished or complete):
It would be helpful to give some reference examples, which follow the guidelines.
Also, we should define the difference between an example and a tutorial. In some cases that's not quite clear to me.
jklymak commentedon Jul 17, 2018
Agree - note that we are also working w/ sphinx-gallery on links to the methods/functions sphinx-gallery/sphinx-gallery#347 which just got merged, so will take a while to release? Adding these back links puts the example in a list under the method (i.e.
https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.plot.html#examples-using-matplotlib-axes-axes-plot) i.e. see the suggested syntax:
#10974 (comment)
story645 commentedon Jul 17, 2018
I go back and forth on this 'cause I do this a lot and get lots of complaints that it's confusing. I think a one liner comment can be very useful here.
chrissshe commentedon Feb 18, 2020
I just created a PR to improve examples/widgets/textbox.py #16549
This is my first contribution to matplotlib. Any feedback are welcome!
tacaswell commentedon Feb 18, 2020
Thanks @chrissshe !
4 remaining items
ggold7046 commentedon Apr 7, 2023
Hello,
I would love to work on this issue if this issue is still open. Could someone guide me; from where to start ?
ggold7046 commentedon Apr 8, 2023
@melissawm , can you help me with this please ? How to find some problems to work on ?
rcomer commentedon Apr 8, 2023
Hi @ggold7046 have you had a look at our contributors’ guide?
https://matplotlib.org/devdocs/devel/contributing.html
ggold7046 commentedon Apr 9, 2023
Hi @rcomer , thanks for the reply. I was not able to find any #11654 PR related issue which needs more explanatory comments to gallery examples. I thought this issue will be a good starting point for me.
jklymak commentedon Apr 9, 2023
@ggold7046 its not clear what you are asking for here. If you have a contribution, code it up and submit as a PR following the guide given above. We don't assign issues.
ggold7046 commentedon Apr 9, 2023
story645 commentedon Apr 9, 2023
Hi @ggold7046, the aim of this issue was that the contributor looks through the gallery and finds which examples they feel need explanation. But, given how open ended this issue is, I'm going to close it since it will overlap with gsod work and hopefully a byproduct of that work will be more specific and targeted issues outlining what isn't working or how to improve specific gallery examples.