Uh oh!
There was an error while loading.Please reload this page.
- Notifications
You must be signed in to change notification settings - Fork7.9k
DOC: move usage tutorial info to Users guide rst#21335
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Uh oh!
There was an error while loading.Please reload this page.
Conversation
| @@ -0,0 +1,151 @@ | |||
| .. _performance: | |||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Just as a point of reference, all I have done is move these verbatim versus tried to edit them.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
👍 For moving this stuff out of the Usage Guide tutorial.
Arebackends.rst andperformance.rst 1:1 copies or did you edit things?
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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 tohttps://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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
Well lets point it there, and open an issue that says it needs work.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
I'm not convinced thatwe 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 useris 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
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).
Uh oh!
There was an error while loading.Please reload this page.
It's verbatim! |
… azp] [skip appveyor]
… azp] [skip appveyor]
… azp] [skip appveyor]
… azp] [skip appveyor]
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
This is good to go, apart from the unrelated renderer changes.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
… azp] [skip appveyor]
… azp] [skip appveyor]
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others.Learn more.
@jklymak should this be squashed before merging?
…335-on-v3.5.xBackport 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).