Doc animation #7589

tacaswell · 2016-12-08T05:38:31Z

The plan (if I have time to get to it is to flesh out the FuncAnimation section with the same example implemented the other 3 ways, but I think that as-is it is still a major improvement.

dopplershift

Thanks for doing this--these are a huge improvement to what I wrote originally. The initial preamble with the example I think should help a lot of people.

One question: Should subclasses be duplicating the documentation of attributes from parent classes?
Otherwise, just a bunch of little stuff.

dopplershift · 2016-12-08T16:54:33Z

doc/api/animation_api.rst

+   FuncAnimation
+   ArtistAnimation
+
+In both cases it is critical to keep a reference to tho instance


tho -> the

dopplershift · 2016-12-08T16:58:19Z

doc/api/animation_api.rst

+       ax.set_ylim(-1, 1)
+       return ln,
+
+   def update(i):


Would it be better to replace i with something making it clear it's a value pulled from the frames kwarg?

dopplershift · 2016-12-08T16:58:47Z

doc/api/animation_api.rst

+
+The second method is to us `functools.partial` to 'bind' artists to
+function.  A third method is to use closures to build up the required
+artists and functions.  A forth method is to create a class.


forth -> fourth

dopplershift · 2016-12-08T17:00:12Z

lib/matplotlib/animation.py

@@ -68,6 +68,8 @@ def adjusted_figsize(w, h, dpi, n):

 # A registry for available MovieWriter classes
 class MovieWriterRegistry(object):
+    '''Registry of of available writer classes by human readable name


double of

dopplershift · 2016-12-08T17:00:43Z

lib/matplotlib/animation.py

@@ -109,6 +111,15 @@ def list(self):
        return list(self.avail.keys())

    def is_available(self, name):
+        '''If given writer is available


How about '''Check if given writer is available.''' ?

dopplershift · 2016-12-08T17:17:14Z

lib/matplotlib/animation.py

+
+          def func(fr: object, *fargs) -> iterable_of_artists:
+
+


Not Sure if this is an extra blank line or one needed to surround the above code block...

dopplershift · 2016-12-08T17:17:48Z

lib/matplotlib/animation.py

+        If `None`, then equivalent to passing ``itertools.count``
+
+    init_func : callable, optional
+


Extra blank line

dopplershift · 2016-12-08T17:18:42Z

lib/matplotlib/animation.py

+       The number of values from `frames` to cache.
+
+    interval : number, optional
+       Delay between frames.  Defaults to 200


Period after 200?

dopplershift · 2016-12-08T17:20:15Z

lib/matplotlib/animation.py

-    used. This function will be called once before the first frame.
+    repeat: bool, optional
+       controls whether the animation should repeat when the sequence
+       of frames is completed.


Add "Defaults to True."

dopplershift · 2016-12-08T17:20:28Z

lib/matplotlib/animation.py

-    *frames* can be a generator, an iterable, or a number of frames.
+    repeat_delay : number, optional
+       If the animation in repeated, adds a delay in milliseconds
+       before repeating the animation.  Defaults to None


"None" -> "None."

QuLogic

Typos and such.

QuLogic · 2016-12-09T08:55:29Z

doc/api/animation_api.rst

+hence the timers), will be garbage collected which will stop the
+animation.
+
+To save an animation use to disk use


Remove first 'use'.

QuLogic · 2016-12-09T08:55:43Z

doc/api/animation_api.rst

+Animation
+=========
+
+The easiest way to make a live animation in mpl is to use one of the


mpl -> Matplotlib

QuLogic · 2016-12-09T08:56:39Z

doc/api/animation_api.rst

+The inner workings of `FuncAnimation` is more-or-less::
+
+  for d in frames:
+     arts = func(d, *fargs)


No reason why this can't say artists instead of arts.

QuLogic · 2016-12-09T08:57:10Z

doc/api/animation_api.rst

+
+'Blitting' is a `old technique
+<https://en.wikipedia.org/wiki/Bit_blit>`__ in computer graphics.  The
+general gist is to take as existing bit map (in our case a mostly


QuLogic · 2016-12-09T08:57:43Z

doc/api/animation_api.rst

+
+   ax = fig.gca()
+
+   def update_blit(arts):


Again, artists for this whole block.

QuLogic · 2016-12-09T09:11:21Z

lib/matplotlib/animation.py

+
+        If a generator function, then must have the signature ::
+
+           def gen_function():


Should be -> int or -> float or anything?

QuLogic · 2016-12-09T09:12:13Z

lib/matplotlib/animation.py

+       The number of values from `frames` to cache.
+
+    interval : number, optional
+       Delay between frames.  Defaults to 200


QuLogic · 2016-12-09T09:12:51Z

lib/matplotlib/animation.py

-    *init_func* is a function used to draw a clear frame. If not given, the
-    results of drawing from the first item in the frames sequence will be
-    used. This function will be called once before the first frame.
+    repeat: bool, optional


Space before colon.

QuLogic · 2016-12-09T09:13:21Z

lib/matplotlib/animation.py

+       other needed events.
+
+    interval : number, optional
+       Delay between frames.  Defaults to 200


QuLogic · 2016-12-09T09:13:31Z

lib/matplotlib/animation.py

+        be disabled for other frames.
+
+    interval : number, optional
+       Delay between frames.  Defaults to 200


tacaswell · 2016-12-11T03:09:08Z

I think I have addressed everything and re-worked the section on writers.

QuLogic

A few more minor things. Otherwise, looks good.

QuLogic · 2016-12-11T03:33:07Z

doc/api/animation_api.rst

+   AVConvFileWriter
+
+
+Fundamentally, a `MovieWriter` does is provide is a way to grab


The 'what' got removed, so now the sentence is a bit off.

And the second 'is' is still there.

QuLogic · 2016-12-11T03:35:01Z

lib/matplotlib/animation.py

@@ -463,6 +483,12 @@ def cleanup(self):
 # Base class of ffmpeg information. Has the config keys and the common set
 # of arguments that controls the *output* side of things.
 class FFMpegBase(object):
+    '''Mixin class for FFMpeg output


It's a bit pedantic, but the first line on each of these newly documented classes sometimes does and sometimes doesn't end with a period.

QuLogic · 2016-12-11T03:36:21Z

lib/matplotlib/animation.py

+        be disabled for other frames.
+
+    interval : number, optional
+       Delay between frames in miliseconds.  Defaults to 200.


miliseconds -> milliseconds

QuLogic · 2016-12-11T03:37:03Z

lib/matplotlib/animation.py

-    of frames is completed.
+    repeat_delay : number, optional
+        If the animation in repeated, adds a delay in milliseconds
+        before repeating the animation.  Defaults to None


This one's missing the backticks on None.

QuLogic · 2016-12-11T03:37:45Z

lib/matplotlib/animation.py

-    used. This function will be called once before the first frame.
+    repeat : bool, optional
+       Controls whether the animation should repeat when the sequence
+       of frames is completed.  Defaults to `True`


This one's missing the period.

QuLogic · 2016-12-11T03:41:08Z

doc/api/animation_api.rst

+sequential frames from the same underlying `~matplotlib.figure.Figure`
+object.  The base class `MovieWriter` implements 3 methods and a
+context manager.  The only difference between the pipe-based and
+file-based writers in the arguments to their respective ``setup``


QuLogic · 2016-12-11T03:41:30Z

doc/api/animation_api.rst

+file to disk.  For example ::
+
+   moviewriter = MovieWriter(...)
+   moveiewriter.setup(fig=fig, 'my_movie.ext', dpi=100)


moveiewriter -> moviewriter

QuLogic · 2016-12-11T03:42:54Z

lib/matplotlib/animation.py

+           default to ``rcParams['animation.codec']``
+
+        bitrate : number, optional
+           Specifies the amount of bits used per second in the


amount -> number

dopplershift

A few truly pedantic things that I would feel back actually requiring before merging...

dopplershift · 2016-12-12T18:02:41Z

lib/matplotlib/animation.py

@@ -1199,7 +1199,7 @@ class TimedAnimation(Animation):

    repeat_delay : number, optional
        If the animation in repeated, adds a delay in milliseconds
-        before repeating the animation.  Defaults to None
+        before repeating the animation.  Defaults to `None`


Pedantic, but no period at the end.

dopplershift · 2016-12-12T18:05:41Z

lib/matplotlib/animation.py


    '''

    def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None,
                 metadata=None):
-        '''
+        '''MovieWriter


No period at the end--though not really a sentence, either. 😁

I intentionally decided against a . here (due to it not being a sentence).

Fair enough.

dopplershift · 2016-12-12T18:07:25Z

lib/matplotlib/animation.py

@@ -1304,24 +1279,24 @@ class ArtistAnimation(TimedAnimation):
       other needed events.

    artists : list
-        with each list entry a collection of artists that
+        With each list entry a collection of artists that


Maybe instead just: Each list entry is a collection...

tacaswell added 3 commits December 7, 2016 22:51

DOC: partially numpydoc-ify animation module

80d8dd8

DOC: use auto summary in animation_api.rst

24c7aad

DOC: start to add animation prose

e465fb7

tacaswell added this to the 2.0 (style change major release) milestone Dec 8, 2016

tacaswell requested review from dopplershift and WeatherGod December 8, 2016 05:38

dopplershift requested changes Dec 8, 2016

View reviewed changes

QuLogic requested changes Dec 9, 2016

View reviewed changes

tacaswell added 3 commits December 10, 2016 21:48

DOC: address comments

ff1e71e

DOC: re-work MovieWriter section a bit

55017cd

DOC: address the rest of the comments

1a6c61c

tacaswell mentioned this pull request Dec 11, 2016

MNT: tweak MovieWriter.saving to be more cautious #7606

Merged

QuLogic reviewed Dec 11, 2016

View reviewed changes

DOC: Fix more typos and minor errors

8e8291c

QuLogic approved these changes Dec 11, 2016

View reviewed changes

dopplershift approved these changes Dec 12, 2016

View reviewed changes

DOC: minor tweaks

4c4779b

dopplershift merged commit 4177725 into matplotlib:v2.x Dec 12, 2016

tacaswell deleted the doc_animation branch December 12, 2016 21:52

		If `None`, then equivalent to passing ``itertools.count``

		init_func : callable, optional


		If a generator function, then must have the signature ::

		def gen_function():

		AVConvFileWriter


		Fundamentally, a `MovieWriter` does is provide is a way to grab

Doc animation #7589

Doc animation #7589

Conversation

tacaswell commented Dec 8, 2016

dopplershift left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

QuLogic left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tacaswell commented Dec 11, 2016

QuLogic left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dopplershift left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dopplershift left a comment •

edited

Loading

QuLogic left a comment •

edited

Loading