DOC: Add summary lines to plot types #27929
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
the
Documentation: plot types
story645
reviewed
Mar 15, 2024
IMHO it's meaningful to give a one-sentence summary on the individual pages, e.g. at https://matplotlib.org/stable/plot_types/basic/plot.html#sphx-glr-plot-types-basic-plot-py > Plot y versus x as lines and/or markers. > > See `plot`. is more helpful than just > See `plot`. Users can already decide if that's the correct function for them and whether it's worth following the link. Also, the first sentence is used in the tooltip on the index page, where the current "See ..." is not helpful. I believe it's ok to just copy the text. Automatic insertion or check for consistency are not worth the added effort. First, these summary lines change rarely. Second, even if we improve the method summary and forget to udpate here, nothing really bad happens; we've maybe a slightly less optimal description here, but that's still way better than no description at all. Semi-OT: I changed the barbs summary from > Plot a 2D field of barbs. to > Plot a 2D field of wind barbs. because, AFAIK these are only used for wind, and that makes the context more clear. People outside of metrology may not know what barbs are so giving that extra context is reasonable.
timhoffm
force-pushed
the
doc-plot-types
branch
from
bb88598
to
a8d8915
Compare
story645
requested changes
Mar 19, 2024
galleries/plot_types/basic/stairs.py
Outdated
| @@ -2,6 +2,7 @@ | |||
| ============== | |||
| stairs(values) | |||
| ============== | |||
| A stepwise constant function as a line with bounding edges or a filled plot. | |||
There was a problem hiding this comment.
This might be silly but I think if we do this then the language should be obnouxisly consistent - the other descriptions start "Plot/Draw/Create"
There was a problem hiding this comment.
At the risk of going off-topic and getting bogged down, I've changed the summary line for stairs().
timhoffm
commented
Mar 19, 2024
story645
approved these changes
Mar 19, 2024
QuLogic
approved these changes
Mar 20, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
IMHO it's meaningful to give a one-sentence summary on the individual pages, e.g. at
https://matplotlib.org/stable/plot_types/basic/plot.html#sphx-glr-plot-types-basic-plot-py
is more helpful than just
Users can already decide if that's the correct function for them and whether it's worth following the link. Also, the first sentence is used in the tooltip on the index page, where the current "See ..." is not helpful.
I believe it's ok to just copy the text. Automatic insertion or check for consistency are not worth the added complexity. First, these summary lines change rarely. Second, even if we improve the method summary and forget to udpate here, nothing really bad happens; we've maybe a slightly less optimal description here, but that's still way better than no description at all.
Semi-OT: I changed the barbs summary from
to
because, AFAIK these are only used for wind, and that makes the context more clear. People outside of metrology may not know what barbs are so giving that extra context is reasonable.