Repository navigation
DOC: move usage tutorial info to Users guide rst - #21335
timhoffm merged 7 commits into
Conversation
Sorry, something went wrong.
| @@ -0,0 +1,151 @@ | |||
| .. _performance: | |||
There was a problem hiding this comment.
Just as a point of reference, all I have done is move these verbatim versus tried to edit them.
Sorry, something went wrong.
timhoffm
left a comment
There was a problem hiding this comment.
👍 For moving this stuff out of the Usage Guide tutorial.
Are backends.rst and performance.rst 1:1 copies or did you edit things?
Sorry, something went wrong.
| Choosing a backend | ||
| ------------------ | ||
|
|
||
| Matplotlib needs a "backend" to render your figure, either in its own GUI window, | ||
| as part of a notebook, or saved as an image to disk. If you need more information on | ||
| choosing a backend, see :ref:`backends`. |
There was a problem hiding this comment.
I don't think we should bother people with backends before they have even plotted their first figure.
Automatic backend detection works mostly fine so that you don't have to care to get started.
Sorry, something went wrong.
There was a problem hiding this comment.
Given the number of questions we get "why doesn't my plot show?" I'm not inclined to agree, and thought a quick mention here would get people looking at the right page.
Sorry, something went wrong.
There was a problem hiding this comment.
Let's be more targeted then: Instead of a general comment on backends, add the following below the plot code:
If no plot shows up, please check [Toubleshooting].
which may link to https://matplotlib.org/devdocs/faq/troubleshooting_faq.html and should get a section on "my plot does not show".
That's probably worth a second PR, because a really helpful guide to "it doesn't work" needs some care.
Sorry, something went wrong.
There was a problem hiding this comment.
Well lets point it there, and open an issue that says it needs work.
Sorry, something went wrong.
There was a problem hiding this comment.
I've changed to
Further details are available in the :doc:`Installation Guide </users/installing>`. If a plot does not show up, we probably could not automatically find an appropriate backend; please check :ref:`troubleshooting-faq`.
I would still suggest that the jargon "backend" appear somewhere on this page because it is key to googling solutions to many problems. However most new users have no idea this very important word even exists.
Sorry, something went wrong.
There was a problem hiding this comment.
I'm not convinced that we probably could not automatically find an appropriate backend; is really the most probable cause or that the term "backend" will stick or be helpful here. - I think that should only be discussed inside troubleshooting, i.e. when the user is having problems.
However, I can accept that sentence if we move it to the "First plot" paragraph. It's sematically in the context of plotting not installation.
Sorry, something went wrong.
There was a problem hiding this comment.
yeah, I already moved this with the latest push.
We can keep this ambiguous:
If a plot does not show up please check :ref:`troubleshooting-faq`.
and get more specific in the trouble shooting faq (or a page linked therein).
Sorry, something went wrong.
|
It's verbatim! |
Sorry, something went wrong.
… azp] [skip appveyor]
… azp] [skip appveyor]
… azp] [skip appveyor]
… azp] [skip appveyor]
timhoffm
left a comment
There was a problem hiding this comment.
This is good to go, apart from the unrelated renderer changes.
Sorry, something went wrong.
… azp] [skip appveyor]
… azp] [skip appveyor]
…335-on-v3.5.x Backport PR #21335 on branch v3.5.x (DOC: move usage tutorial info to Users guide rst)
DOC: move usage tutorial info to Users guide rst
PR Summary
tutorials/usage.py had some useful information buried that was not really a "tutorial", was almost all written in rst, and in my opinion deserve their own TOC in the users/ section. The organization is flat for now, but will be re-organized (I hope) when #21251 goes in.
PR Checklist