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

story645 · 2020-05-21T08:40:04Z

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

dstansby

One minor suggestion, but these all look like good improvements

doc/users/interactive.rst

tacaswell

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

doc/users/interactive.rst

tacaswell · 2020-05-21T14:20:52Z

doc/users/interactive.rst

- 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


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.

tacaswell · 2020-05-21T14:29:47Z

doc/users/interactive.rst

- 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


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?

tacaswell · 2020-05-21T14:31:31Z

doc/users/interactive.rst

-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)``, 


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 ...

tacaswell · 2020-05-21T14:32:26Z

doc/users/interactive.rst

+:ref:`key bindings <key-event-handling>`:

-`.pyplot.figure`
+* `.pyplot.figure`


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

tacaswell · 2020-05-21T14:33:22Z

doc/users/interactive.rst

-<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, 


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.

tacaswell · 2020-05-21T14:35:49Z

doc/users/interactive.rst


 ::
-
-   user@machine:~ $ ipython


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

doc/users/interactive.rst

tacaswell · 2020-05-21T14:38:49Z

doc/users/interactive.rst


-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; 


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

QuLogic · 2020-05-21T21:16:54Z

doc/users/interactive.rst

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


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.

QuLogic · 2020-05-21T21:24:51Z

doc/users/interactive.rst

- 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


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.

QuLogic · 2020-05-21T21:27:39Z

doc/users/interactive.rst

-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)``, 


In any case,

QuLogic · 2020-05-21T21:27:51Z

doc/users/interactive.rst


-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 part of -> from

doc/users/interactive.rst

tacaswell · 2020-06-08T22:02:00Z

doc/users/interactive.rst


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


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

doc/users/interactive.rst

tacaswell · 2020-06-09T17:49:47Z

Getting this sorted should not block tagging the RC.

outdated

story645 · 2020-06-12T23:36:10Z

folks are welcome to squash merge this

…angauge

tacaswell

Anyone can merge on green.

doc/users/interactive.rst

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

doc/users/interactive.rst Outdated Show resolved Hide resolved

doc/users/interactive.rst Outdated Show resolved Hide resolved

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

doc/users/interactive.rst Outdated Show resolved Hide resolved

doc/users/interactive.rst Outdated Show resolved Hide resolved

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

tacaswell reviewed Jun 8, 2020

View reviewed changes

doc/users/interactive.rst Outdated Show resolved Hide resolved

tacaswell reviewed Jun 8, 2020

View reviewed changes

doc/users/interactive.rst Outdated Show resolved Hide resolved

tacaswell reviewed Jun 8, 2020

View reviewed changes

doc/users/interactive.rst Outdated Show resolved Hide resolved

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

doc/users/interactive.rst Outdated Show resolved Hide resolved

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

	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)``,

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

Uh oh!

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!

tacaswell left a comment

Choose a reason for hiding this comment

Uh oh!