Skip to content

DOC: Add more explanatory comments to gallery examples #11654

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
story645 opened this issue Jul 13, 2018 · 14 comments
Closed

DOC: Add more explanatory comments to gallery examples #11654

story645 opened this issue Jul 13, 2018 · 14 comments
Labels
Documentation Good first issue Open a pull request against these issues if there are no active ones!
Milestone
v3.7-doc

Comments

@story645
Copy link
Member

story645 commented Jul 13, 2018 •
edited
Loading

@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.
@story645 story645 added Documentation Good first issue Open a pull request against these issues if there are no active ones! labels Jul 13, 2018
@gabru-md
Copy link
Contributor

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
Copy link
Member Author

Go for it! This issue is fairly broad, so supports multiple people working on it.

Merged
6 tasks
@timhoffm
Copy link
Member

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):

  • Describe the purpose of the example in 1-2 sentences at the top.
  • If suitable, add a section to describe what is done in more detail.
  • Don't describe functionality that's not the main topic of the example (e.g. don't describe the creation of the legend, if it's only in the example to make the generated plot more understandable).
  • Do not describe what's already in docstrings unless it's essential for the understanding of the example. You may link to the docstring.
  • The code itself should be kept as readable as possible.
  • Do not add long explanations as code comments. Instead, put the explanation before the code, or if really necessary, use multiple code blocks with text in between.
  • You may use some short explanatory comments within the code (a good example is the aspect comment in the pie chart example above). But do not clutter the code with too many comments.

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
Copy link
Member

jklymak commented 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
Copy link
Member Author

Don't describe functionality that's not the main topic of the example (e.g. don't describe the creation of the legend, if it's only in the example to make the generated plot more understandable).

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.

This was referenced Jan 10, 2019
Merged
Merged
@mollyrossow mollyrossow mentioned this issue Feb 19, 2019
Merged
6 tasks
@tacaswell tacaswell added this to the v3.0-doc milestone Feb 20, 2019
@tacaswell tacaswell modified the milestones: v3.0-doc, v3.1-doc Jul 3, 2019
@chrissshe chrissshe mentioned this issue Feb 18, 2020
Merged
6 tasks
@chrissshe
Copy link
Contributor

chrissshe commented Feb 18, 2020 •
edited
Loading

I just created a PR to improve examples/widgets/textbox.py #16549

This is my first contribution to matplotlib. Any feedback are welcome!

@tacaswell
Copy link
Member

Thanks @chrissshe !

@tacaswell tacaswell modified the milestones: v3.1-doc, 3.2-doc Mar 15, 2020
@QuLogic QuLogic modified the milestones: 3.2-doc, v3.3-doc Jul 17, 2020
@QuLogic QuLogic modified the milestones: v3.3-doc, v3.5.0 Jan 28, 2021
@QuLogic QuLogic modified the milestones: v3.5.0, v3.6.0 Sep 25, 2021
This was referenced Dec 21, 2021
Merged
Closed
Merged
@QuLogic QuLogic modified the milestones: v3.6.0, v3.7.0 Jul 8, 2022
@ksunden ksunden modified the milestones: v3.7.0, v3.7.1 Feb 14, 2023
@QuLogic QuLogic modified the milestones: v3.7.1, v3.7-doc Mar 4, 2023
@ggold7046
Copy link

ggold7046 commented Apr 7, 2023 •
edited
Loading

Hello,

I would love to work on this issue if this issue is still open. Could someone guide me; from where to start ?

@ggold7046
Copy link

@melissawm , can you help me with this please ? How to find some problems to work on ?

@rcomer
Copy link
Member

rcomer commented Apr 8, 2023

Hi @ggold7046 have you had a look at our contributors’ guide?
https://matplotlib.org/devdocs/devel/contributing.html

@ggold7046
Copy link

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
Copy link
Member

jklymak commented 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
Copy link

ggold7046 commented Apr 9, 2023 via email

@story645
Copy link
Member Author

story645 commented 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.

@story645 story645 closed this as completed Apr 9, 2023
@timhoffm timhoffm mentioned this issue Apr 13, 2023
Closed
6 tasks
@story645 story645 mentioned this issue Jul 13, 2023
Merged
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Good first issue Open a pull request against these issues if there are no active ones!
Projects
None yet
Milestone
v3.7-doc
Development

No branches or pull requests
10 participants
@tacaswell @QuLogic @story645 @jklymak @ksunden @timhoffm @rcomer @chrissshe @gabru-md @ggold7046