Distinguish AbstractMovieWriter and MovieWriter in docs. #21948
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tacaswell
approved these changes
Dec 14, 2021
tacaswell
reviewed
Dec 14, 2021
timhoffm
reviewed
Dec 14, 2021
doc/api/animation_api.rst
Outdated
Comment on lines
214
to
218
| Fundamentally, an `AbstractMovieWriter` provides a way to grab sequential | ||
| frames from the same underlying `~matplotlib.figure.Figure` object. The | ||
| base `AbstractMovieWriter` class 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. |
There was a problem hiding this comment.
Suggested change
| Fundamentally, an `AbstractMovieWriter` provides a way to grab sequential | |
| frames from the same underlying `~matplotlib.figure.Figure` object. The | |
| base `AbstractMovieWriter` class 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` object. They all provide 3 methods | |
| that must be called in sequence: | |
| - `~-AbstractMovieWriter.setu 8000 p` 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. |
There was a problem hiding this comment.
IMHO it doesn't make sense to specifically mention AbstractMovieWriter because nobody will use that class. Instead, we can more informally say "all writer classes".
Note also that #21954 moves the ineritance diagram here and adds missing classes, which should make the relations more clear.
doc/api/animation_api.rst
Outdated
Comment on lines
220
to
223
| The `~AbstractMovieWriter.setup` method is used to prepare the writer (possibly | ||
| opening a pipe), successive calls to `~.AbstractMovieWriter.grab_frame` capture | ||
| a single frame at a time and `~.AbstractMovieWriter.finish` finalizes the movie | ||
| and writes the output file to disk. For example :: |
There was a problem hiding this comment.
Suggested change
| The `~AbstractMovieWriter.setup` method is used to prepare the writer (possibly | |
| opening a pipe), successive calls to `~.AbstractMovieWriter.grab_frame` capture | |
| a single frame at a time and `~.AbstractMovieWriter.finish` finalizes the movie | |
| and writes the output file to disk. For example :: | |
| Example:: |
|
Thanks @timhoffm, I've integrated your changes, they look great. I also updated an example a bit earlier in the text to use 4-space indents. |
Some docs of AbstractMovieWriter are still written as if referring to MovieWriter (which could be better named PipeMovieWriter, i.e. writers that pipe frame data to a running subprocess). This probably dates back to when AbstractMovieWriter was not a thing yet. Fix that.
dstansby
approved these changes
Dec 15, 2021
timhoffm
approved these changes
Dec 15, 2021
meeseeksmachine
pushed a commit
to meeseeksmachine/matplotlib
that referenced
this pull request
Dec 15, 2021
…ieWriter in docs.
QuLogic
added a commit
that referenced
this pull request
Dec 16, 2021
…948-on-v3.5.x Backport PR #21948 on branch v3.5.x (Distinguish AbstractMovieWriter and MovieWriter in docs.)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Some docs of AbstractMovieWriter are still written as if referring to
MovieWriter (which could be better named PipeMovieWriter, i.e. writers
that pipe frame data to a running subprocess). This probably dates
back to when AbstractMovieWriter was not a thing yet.
Fix that.
PR Summary
PR Checklist
Tests and Styling
pytestpasses).flake8-docstringsand runflake8 --docstring-convention=all).Documentation
doc/users/next_whats_new/(follow instructions in README.rst there).doc/api/next_api_changes/(follow instructions in README.rst there).