DOC: Update Basic Usage tutorial #21800
Conversation
|
Lets maybe get #21794 in first... |
|
@jklymak oops, sorry - didn't see it when I started this one. Yes of course, will rebase then if necessary. |
|
many of these edits are great, and thanks for catching the spelling errors! We need to be careful about mission creep in this document. You've suggested adding multiple axises/secondary axis to the figure. One could also add more colorbar, inset axes, etc etc. Maybe instead of full examples, lets just have some text that links to relevant examples for twinx and secondary_ax? |
You're right, but IMHO a second y axis may be used more frequently than say math text or annotations (especially when you are used to Excel where you can send a data series with just one click to a second y axis on the right). I'd love to just refer to some tutorial on secondary, twin and shared and parasite axes (the latter two I left out intentionally), but there is none. So I tried to illustrate the concepts with two minimalistic examples as a short example is easier (at least for me) than describing the functionality in words. Maybe we can combine the two paragraphs into one and show the examples side by side to make it even more concise (athough subplot are only introduced further down the tutorial, but the color mapped data section also uses subplots). But in the end I'm also happy with just the links to some examples. |
|
Well, lets let others weigh in. My vote would be to trim rather than to add ;-) There are quite a few twinx examples: https://matplotlib.org/stable/api/_as_gen/matplotlib.axes.Axes.twinx.html and there is a seocndary_axis example: https://matplotlib.org/stable/gallery/subplots_axes_and_figures/secondary_axis.html#sphx-glr-gallery-subplots-axes-and-figures-secondary-axis-py |
|
@jklymak sure, no problem. Just in case: this is a less space-consuming version by putting the plots side by side:
|
|
I'm in favor of taking this extra section. I think twinned and secondary axes are on the same level of importance with annotations (but a bit behind math text) ;) This is something that is particularly hard to describe to google so having a picture and link is 👍 |
Is that a case for making an intermediate usage? Where basic is stripped down to how do I make one thing & label it, and intermediate is more of a grab bag of very commonly asked for things? |
|
Please, no more grab bags! But I'm warming to this section particular if it links out to the other examples. If the subject requires expansion or unification of those examples a new tutorial might make sense. |
af17fc6 to
2a62854
Compare
|
@jklymak Sorry for being a pain in the neck, but I also changed matplotlib/lib/matplotlib/figure.py Lines 2204 to 2210 in 505cdff |
|
No, not a pain - I forgot about that change. |
- fix typos and PEP8 (line 338) - apply terminology and unify capitalization acc. to https://matplotlib.org/stable/devel/style_guide.html#terminology - replace -- by en dash (–), as smartquotes is set to False in conf.py - explicitly apply ConciseDateFormatter so that it's clear why the date axis is formatted the way it is(examples\ticks\date_concise_formatter.py registers the ConciseDateConverter and when the documentation is being built, this example is processed before the tutorials and hence the registered converter is still in effect) - remove redundant redefinition of x at line 246 and move definition of xdata at line 208 to where it is used
Secondary and twin axes are rather important (although not necessarily very basic) so they should be shortly mentioned with links to the API docs and some more detailed examples.
as the former is discouraged, see https://matplotlib.org/3.5.0/api/figure_api.html#matplotlib.figure.Figure
regarding implicit/explicit and pyplot/object oriented style
…800-on-v3.5.x Backport PR #21800 on branch v3.5.x (DOC: Update Basic Usage tutorial)
…800-on-v3.5.0-doc Backport PR #21800 on branch v3.5.0-doc (DOC: Update Basic Usage tutorial)
PR Summary
1st commit: some minor fixes:
https://matplotlib.org/stable/devel/style_guide.html#terminology
smartquotesis set toFalsein conf.pyConciseDateFormatterso that it's clear why the dateaxis is formatted the way it is (examples\ticks\date_concise_formatter.py
registers the ConciseDateConverter and when the documentation is being
built, this example is processed before the tutorials and hence the
registered converter is still in effect)
@jklymak I hope you don't mind my rather intrusive terminology edits, just trying to follow the style guide. I'm not happy with adding the ConciseDateConverter but without doing so the tutorial seems a bit misleading or confusing if someone is trying to reproduce this example and gets a different result. It would be better to undo the converter registration but I couldn't think of a good way to do so.
2nd commit: add additional axes section
Secondary and twin axes are rather important (although not necessarily
very basic) so they should be shortly mentioned with links to the API
docs where more detailed examples are linked (unfortunately there's no
tutorial on secondary and twin axes to refer to).
@jklymak Maybe you can rephrase these two short sections into clearer language (sorry for my limited command of English when it comes to writing documentation)
PR Checklist
Tests and Styling
[n/a] Has pytest style unit tests (and
pytestpasses).flake8-docstringsand runflake8 --docstring-convention=all).Documentation
[n/a] New features are documented, with examples if plot related.
[n/a] New features have an entry in
doc/users/next_whats_new/(follow instructions in README.rst there).[n/a] API changes documented in
doc/api/next_api_changes/(follow instructions in README.rst there).[n/a] Documentation is sphinx and numpydoc compliant (the docs should build without error).