Removed idiomatic constructs from interactive figures docs by story645 · Pull Request #17471 · matplotlib/matplotlib · GitHub

Kind of a followup to #4779,

stripped out some idiomatic language
cleaned up Jupyter capitalization
put the descriptions before the code in the code snippets (my docs don't build so I don't know if it renders the snippets...),
reworded some things to hopefully be clearer

One minor suggestion, but these all look like good improvements

I agree with most of the wording changes, but some of the changes make the text less accurate.

The updates will only happen while show or pause are blocking and well cease after they return. You can also get an update by calling fig.canvas.flush_events or by manually running the event loop.

Additionally, when not in interactive mode the stale hook is turned off so mutating the figure does not trigger draw_idle.

I'm so unclear about what you're getting at here/how these suggestions translate into user facing docs.

I think that "returns" is the correct language here. Processes exit, functions return.

I hate both and think neither is super clear, especially here where it's not super clear that pyplot.show is being talked about in the context of it being a function.

"exits" is definitely incorrect for a function. Perhaps pyplot.show() (with parentheses) would make things clearer?

Suggested change

      
            The figures will also be "live" if you use ``pyplot.show(block=True)``, 
          
            It any case the figures will be "live" if you use ``pyplot.show(block=True)``,

In any case,

in any case is an ambigious reference 'cause it's not clear what the cases are ...

I would prefer to leave these as definition lists rather than bullet points.

I use "live" here to try and disambiguate it from the several other meanings of the word "interactive".

"live" needs to be defined on first usage - I try to do it a little later but I can pull it up here.

I think it is helpful to identify that we are in an IPython session, we should not assume that our readers well recognize the prompt as IPython from the style.

We say that it's IPython in the narrative, but I'm fine putting this line back in. I just don't want them getting tripped up on all the details of your particular Ipython install

Suggested change

      
            which uses the `.backend_nbagg` backend which is installed by Matplotlib; 
          
            which uses the `.backend_nbagg` backend which part of Matplotlib;

"is installed by" implies it is an external package that we depend on which it is a first-party backend.

which part of -> from

Looking at this again, "this way" previously had (when this was one paragraph) some tie in to the 'Current Figure'/'Current Axes' textually, but it doesn't actually in code. So I think this line needs a clarification of what 'this way' is, or this paragraph needs to go before the paragraph on 'current'-ness.

That assumes you're in a prompt...

Though in a script, if plt.ion() is called, then plt.show() immediately returns, and your script exits because nothing is running, so I guess you do end up at a prompt eventually (just not Python's).

Yeah, this is my frustration w/ the plt.show() docs - they kind of assume a prompt too and it's really unclear.

Not really? It just says show won't return, and nothing about prompts.

First line of the show docs:

When running in ipython with its pylab mode, display all figures and return to the ipython prompt

And the rest of the docs use the language of blocking but don't saw what's being blocked.

That is no longer the first line of show() docs.

🤦

In any case,

which part of -> from

It is the automatic re-draw that is disabled, if you have a prompt you can always interactively modify it (even with out the event loop integration), the user then has to intentionally trigger re-draws or spin the event loop.

I'm using interactive modification == automatic redraw, but will clarify that

Getting this sorted should not block tagging the RC.

outdated

folks are welcome to squash merge this

…angauge

Anyone can merge on green.

Co-authored-by: Thomas A Caswell <tcaswell@gmail.com> Co-authored-by: David Stansby <dstansby@gmail.com> Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

story645 added the Documentation label May 21, 2020

dstansby approved these changes May 21, 2020

View reviewed changes

Comment thread doc/users/interactive.rst Outdated

Comment thread doc/users/interactive.rst Outdated

tacaswell previously requested changes May 21, 2020

View reviewed changes

tacaswell added this to the v3.3.0 milestone May 21, 2020

QuLogic reviewed May 21, 2020

View reviewed changes

tacaswell added the Release critical For bugs that make the library unusable (segfaults, incorrect plots, etc) and major regressions. label May 27, 2020

story645 force-pushed the interactivity branch from eeeafe9 to e7a4fc3 Compare May 28, 2020 02:06

story645 added 3 commits May 28, 2020 01:49

Update documenting_mpl.rst

9ada3fe

Update documenting_mpl.rst

28c3b4f

Merge branch 'winbuild' of github.com:story645/matplotlib

05241d1

QuLogic approved these changes May 30, 2020

View reviewed changes

Comment thread doc/users/interactive.rst Outdated

Comment thread doc/users/interactive.rst Outdated

QuLogic requested a review from tacaswell May 30, 2020 08:17

tacaswell reviewed Jun 8, 2020

View reviewed changes

Comment thread doc/users/interactive.rst Outdated

tacaswell reviewed Jun 8, 2020

View reviewed changes

Comment thread doc/users/interactive.rst Outdated

tacaswell reviewed Jun 8, 2020

View reviewed changes

Comment thread doc/users/interactive.rst Outdated

story645 added 2 commits June 15, 2020 15:52

Merge branch 'master' of github.com:matplotlib/matplotlib

1f39173

cleaned up idioms, restructured the code example, stripped down sme l…

bd5d63a

…angauge

story645 force-pushed the interactivity branch from 540c643 to 43032c6 Compare June 15, 2020 21:45

tacaswell approved these changes Jun 15, 2020

View reviewed changes

QuLogic reviewed Jun 16, 2020

View reviewed changes

Comment thread doc/users/interactive.rst Outdated

Update doc/users/interactive.rst

e6411d4

Co-authored-by: Thomas A Caswell <tcaswell@gmail.com> Co-authored-by: David Stansby <dstansby@gmail.com> Co-authored-by: Elliott Sales de Andrade <quantum.analyst@gmail.com>

tacaswell force-pushed the interactivity branch from 43032c6 to e6411d4 Compare June 16, 2020 03:41

QuLogic merged commit f8e4012 into matplotlib:master Jun 16, 2020

story645 deleted the interactivity branch June 16, 2020 17:41

-              - pyplot.show runs the GUI event loop and does not return until all of
-                the plot windows are closed
+              - newly created figures and changes to figures are not displayed until
+              `.pyplot.show` is called again or `.pyplot.pause` exits

-              <https://github.com/matplotlib/ipympl>`__.  For the figures to be
-              "live" the GUI event loop will need to be integrated with your prompt. The
-              simplest way is to use IPython (see :ref:`below <ipython-pylab>`).
+              <https://github.com/matplotlib/ipympl>`__.  For the figures to be interactive,

-              - pyplot.show will return immediately by default
+              - newly created figures will be displayed immediately
+              - figures will automatically redraw when elements are changed
+              - `pyplot.show` displays the figures and immediately returns to the prompt

-              - whether `.pyplot.show` returns immediately or after all of the
-                figures have been closed when given no arguments
+              - when `.pyplot.show` exits: immediately, or after all of the figures have been closed if given no arguments

-              loop in some other way.
+              at the prompt, regardless of pyplot's "interactive mode".
+              The figures will also be "live" if you use ``pyplot.show(block=True)``,

	The figures will also be "live" if you use ``pyplot.show(block=True)``,
	It any case the figures will be "live" if you use ``pyplot.show(block=True)``,

+              :ref:`key bindings <key-event-handling>`:
-              `.pyplot.figure`
+              * `.pyplot.figure`

-              which uses the `.backend_nbagg` backend which ships with Matplotlib.
-              However nbagg does not work in Jupyter Lab.
+              which uses the `.backend_nbagg` backend which is installed by Matplotlib;

	which uses the `.backend_nbagg` backend which is installed by Matplotlib;
	which uses the `.backend_nbagg` backend which part of Matplotlib;

+              appropriate.
+              Matplotlib keeps a reference to all of the open figures
               created this way so they will not be garbage collected.  You can close

-              it will be reflected immediately. If you wish to disable this behavior
-              use
+              If you wish to disable interactive modification of the plot:


		::

		user@machine:~ $ ipython

Removed idiomatic constructs from interactive figures docs by story645 · Pull Request #17471 · matplotlib/matplotlib · GitHub

Repository navigation

Removed idiomatic constructs from interactive figures docs - #17471

Removed idiomatic constructs from interactive figures docs#17471QuLogic merged 6 commits intomatplotlib:mastermatplotlib/matplotlib:masterfrom story645:interactivitystory645/matplotlib:interactivityCopy head branch name to clipboard

Conversation

story645 commented May 21, 2020

Uh oh!

dstansby left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tacaswell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

tacaswell commented Jun 9, 2020

Uh oh!

story645 commented Jun 12, 2020

Uh oh!

Removed idiomatic constructs from interactive figures docs#17471
QuLogic merged 6 commits into
matplotlib:masterfrom
story645:interactivity