DOC: move usage tutorial info to Users guide rst #21335
Conversation
| @@ -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.
doc/users/getting_started.rst
Outdated
| 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.
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.
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.
There was a problem hiding this comment.
Well lets point it there, and open an issue that says it needs work.
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.
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.
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).
|
It's verbatim! |
… azp] [skip appveyor]
… azp] [skip appveyor]
… azp] [skip appveyor]
… azp] [skip appveyor]
… 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.pyhad 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 theusers/section. The organization is flat for now, but will be re-organized (I hope) when #21251 goes in.PR Checklist
pytestpasses).flake8on changed files to check).flake8-docstringsand runflake8 --docstring-convention=all).doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).