DOC: rename Usage Guide to Basic Usage and update #21641
Conversation
0b339f7 to
85de443
Compare
57f3c80 to
908ffca
Compare
|
rebased on main... |
|
|
||
|
|
||
| def my_plotter(ax, data1, data2, param_dict): | ||
| """ | ||
| A helper function to make a graph | ||
| A helper function to make a graph. |
There was a problem hiding this comment.
I have mixed feeling about dropping the docstring. On one hand, I see the reason to make it terser, on the other hand we should model best practices.
There was a problem hiding this comment.
I don't feel strongly about this, and am happy to add it back in. However, I think for a little in-script utility its OK to not have a numpydoc compliant docstring, and I found it distracting for a tutorial.
tutorials/introductory/usage.py
Outdated
| ax.set_xlabel('Smarts') | ||
| ax.set_ylabel('Probability') | ||
| ax.set_title('Histogram of IQ') | ||
| ax.text(60, .025, r'$\mu=100,\ \sigma=15$') |
There was a problem hiding this comment.
| ax.set_xlabel('Smarts') | |
| ax.set_ylabel('Probability') | |
| ax.set_title('Histogram of IQ') | |
| ax.text(60, .025, r'$\mu=100,\ \sigma=15$') | |
| ax.set_xlabel('Value') | |
| ax.set_ylabel('Probability') | |
| ax.set_title('Histogram of normal distribution') | |
| ax.text(60, .025, r'$\mu=100,\ \sigma=15$') |
There was a problem hiding this comment.
Changed to aardvark length (with a caveat that the distribution was not real, though I changed the mean to be correct for aardvarks).
There was a problem hiding this comment.
I think this a big improvement.
I left one additional comment changing the text in an example (IQ can be controversial and is non-material to the point we are trying to make so might as well avoid courting controversy), but won't block merging over that.
@jklymak can self-merge either taking the suggestion or not.
|
Yeah that one was left over from before so I didn't change it. But I wondered about it as well and am happy to switch to aardvark length or something. We actually have a gender one somewhere which strikes me as even more potentially contentious - i will try and remember to open an issue for that |
e95d4e5 to
d39c4d4
Compare
|
Owee, I'm MrMeeseeks, Look at me. There seem to be a conflict, please backport manually. Here are approximate instructions:
And apply the correct labels and milestones. Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon! Remember to remove the If these instructions are inaccurate, feel free to suggest an improvement. |
|
Owee, I'm MrMeeseeks, Look at me. There seem to be a conflict, please backport manually. Here are approximate instructions:
And apply the correct labels and milestones. Congratulations — you did some good work! Hopefully your backport PR will be tested by the continuous integration and merged soon! Remember to remove the If these instructions are inaccurate, feel free to suggest an improvement. |
DOC: rename Usage Guide to Basic Usage and update
…3.5.0-doc Backport PR #21641: DOC: rename Usage Guide to Basic Usage and update
PR Summary
Renames Usage Guide tutorial to Basic Usage (tutorials/introductory/usage.py). This adds extensively to this guide to provide a short overview of how to use Matplotlib, with links to other tutorials or examples where appropriate or necessary. This is meant to be on par with the pyplot tutorial, but doesn't follow it slavishly.
History
This page used to have a bunch of explanatory material. A lot of this was moved in #21335 to
/docs/usersleaving this page quite thin. There is already the pyplot tutorial, and the "lifecycle of a plot" tutorial, but the pyplot tutorial is not the style we'd prefer people to use, and "lifecycle" goes deep in a couple of directions. (Actually, I'd like to remove that tutorial as well, or make it more "scientific" by not just making a bar plot of all things, but that is lower priority)Goal
Not completeness, but enough ideas of what the library can do to point users to more complete resources.
Use default styles wherever possible. Only exception are the figure sizes, which are usually unsuitable for a website tutorial (in my opinion).
If there is a major part of the library for basic usage, feel free to comment.
Outline:
Basic usage
[NOTE: depends on #21631 - I'll rebase when that is done. Only file to change is
tutorials/introductory/usage.py]PR Checklist
Tests and Styling
pytestpasses).flake8-docstringsand runflake8 --docstring-convention=all).Documentation
doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).