Merge pull request #21948 from anntzer/animdoc

timhoffm · web-flow · commit ee3cb9a6f0ed · 2021-12-15T19:57:52.000+01:00
Distinguish AbstractMovieWriter and MovieWriter in docs.
diff --git a/doc/api/animation_api.rst b/doc/api/animation_api.rst
@@ -51,9 +51,9 @@ supported.
 The inner workings of `FuncAnimation` is more-or-less::
 
   for d in frames:
-     artists = func(d, *fargs)
-     fig.canvas.draw_idle()
-     fig.canvas.start_event_loop(interval)
+      artists = func(d, *fargs)
+      fig.canvas.draw_idle()
+      fig.canvas.start_event_loop(interval)
 
 with details to handle 'blitting' (to dramatically improve the live
 performance), to be non-blocking, not repeatedly start/stop the GUI
@@ -207,16 +207,18 @@ debug.
    FFMpegFileWriter
    ImageMagickFileWriter
 
-Fundamentally, a `MovieWriter` provides a way to grab 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 is in the
-arguments to their respective ``setup`` methods.
+The writer classes provide a way to grab sequential frames from the same
+underlying `~matplotlib.figure.Figure`.  They all provide three methods that
+must be called in sequence:
 
-The ``setup()`` method is used to prepare the writer (possibly opening
-a pipe), successive calls to ``grab_frame()`` capture a single frame
-at a time and ``finish()`` finalizes the movie and writes the output
-file to disk.  For example ::
+- `~.AbstractMovieWriter.setup` prepares the writer (e.g. opening a pipe).
+  Pipe-based and file-based writers take different arguments to ``setup()``.
+- `~.AbstractMovieWriter.grab_frame` can then be called as often as
+  needed to capture a single frame at a time
+- `~.AbstractMovieWriter.finish` finalizes the movie and writes the output
+  file to disk.
+
+Example::
 
    moviewriter = MovieWriter(...)
    moviewriter.setup(fig, 'my_movie.ext', dpi=100)
@@ -226,14 +228,14 @@ file to disk.  For example ::
    moviewriter.finish()
 
 If using the writer classes directly (not through `Animation.save`), it is
-strongly encouraged to use the `~MovieWriter.saving` context manager ::
+strongly encouraged to use the `~.AbstractMovieWriter.saving` context manager::
 
   with moviewriter.saving(fig, 'myfile.mp4', dpi=100):
       for j in range(n):
           update_figure(j)
           moviewriter.grab_frame()
 
-to ensures that setup and cleanup are performed as necessary.
+to ensure that setup and cleanup are performed as necessary.
 
 Examples
 --------
diff --git a/lib/matplotlib/animation.py b/lib/matplotlib/animation.py
@@ -156,19 +156,17 @@ def __getitem__(self, name):
 
 class AbstractMovieWriter(abc.ABC):
     """
-    Abstract base class for writing movies. Fundamentally, what a MovieWriter
-    does is provide is a way to grab frames by calling grab_frame().
+    Abstract base class for writing movies, providing a way to grab frames by
+    calling `~AbstractMovieWriter.grab_frame`.
 
-    setup() is called to start the process and finish() is called afterwards.
-
-    This class is set up to provide for writing movie frame data to a pipe.
-    saving() is provided as a context manager to facilitate this process as::
+    `setup` is called to start the process and `finish` is called afterwards.
+    `saving` is provided as a context manager to facilitate this process as ::
 
         with moviewriter.saving(fig, outfile='myfile.mp4', dpi=100):
             # Iterate over frames
             moviewriter.grab_frame(**savefig_kwargs)
 
-    The use of the context manager ensures that setup() and finish() are
+    The use of the context manager ensures that `setup` and `finish` are
     performed as necessary.
 
     An instance of a concrete subclass of this class can be given as the
