[Doc]: Arguments of FFMpegFileWriter not clear.

[baloe]

Documentation Link

https://matplotlib.org/stable/api/_as_gen/matplotlib.animation.FFMpegFileWriter.html

Problem

There is no word on what arguments to set via *args, **kwargs.

Also, I am wondering how to control where the temporary frame files are stored. I was unable to find them in my /tmp directory
okay, that is actually rather clear (frame_prefix in setup)

Suggested improvement

List arguments or refer to class whose initialization arguments are to be used.

[tacaswell]

The task here is to sort out why

matplotlib/lib/matplotlib/animation.py

Lines 267 to 288 in c33557d

	def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None,
	metadata=None):
	"""
	Parameters
	----------
	fps : int, default: 5
	Movie frame rate (per second).
	codec : str or None, default: :rc:`animation.codec`
	The codec to use.
	bitrate : int, default: :rc:`animation.bitrate`
	The bitrate of the movie, in kilobits per second. Higher values
	means higher quality movies, but increase the file size. A value
	of -1 lets the underlying movie encoder select the bitrate.
	extra_args : list of str or None, optional
	Extra command-line arguments passed to the underlying movie
	encoder. The default, None, means to use
	:rc:`animation.[name-of-encoder]_args` for the builtin writers.
	metadata : dict[str, str], default: {}
	A dictionary of keys and values for metadata to include in the
	output file. Some keys that may be of use include:
	title, artist, genre, subject, copyright, srcform, comment.
	"""

is not forwarded to

matplotlib/lib/matplotlib/animation.py

Lines 389 to 391 in c33557d

	def __init__(self, *args, **kwargs):
	super().__init__(*args, **kwargs)
	self.frame_format = mpl.rcParams['animation.frame_format']

and rendered for the FFMpegFileWriter and fix it!

[QuLogic]

FFMpegFileWriter.__doc__ prints the class docstring; FFMpegFileWriter.__init__.__doc__ is empty, but FFMpegFileWriter? in ipython does print out the correct docstring for both. I'm not sure what's missing there.

[timhoffm]

Maybe we should adopt numpydocs convention to always document init parameters in the class docstring https://numpydoc.readthedocs.io/en/latest/format.html#class-docstring

[oscargus]

There is also quite a bit of failing cross-references in the animation docs that one possibly can try to sort out at the same time.

[kkoutris]

I would like to work on this issue. Can someone guide me a bit to resolve it?

[Baalkikhaal]

Hi all, I am interested in working on this issue. Working towards my first contribution to matplotlib project, I have successfully set up matplotlib for development. As of now, I am competent in reading classes and their inheritance hierarchies. Therefore, I am hoping I can solve this issue.

As suggested by @tacaswell,

The task here is to sort out why

matplotlib/lib/matplotlib/animation.py

Lines 267 to 288 in c33557d

	def __init__(self, fps=5, codec=None, bitrate=None, extra_args=None,
	metadata=None):
	"""
	Parameters
	----------
	fps : int, default: 5
	Movie frame rate (per second).
	codec : str or None, default: :rc:`animation.codec`
	The codec to use.
	bitrate : int, default: :rc:`animation.bitrate`
	The bitrate of the movie, in kilobits per second. Higher values
	means higher quality movies, but increase the file size. A value
	of -1 lets the underlying movie encoder select the bitrate.
	extra_args : list of str or None, optional
	Extra command-line arguments passed to the underlying movie
	encoder. The default, None, means to use
	:rc:`animation.[name-of-encoder]_args` for the builtin writers.
	metadata : dict[str, str], default: {}
	A dictionary of keys and values for metadata to include in the
	output file. Some keys that may be of use include:
	title, artist, genre, subject, copyright, srcform, comment.
	"""

is not forwarded to

matplotlib/lib/matplotlib/animation.py

Lines 389 to 391 in c33557d

	def __init__(self, *args, **kwargs):
	super().__init__(*args, **kwargs)
	self.frame_format = mpl.rcParams['animation.frame_format']

and rendered for the FFMpegFileWriter and fix it!

the MovieWriter superclasses FFMpegFileWriter via an intermediate FileMovieWriter class.
If class decorators have something to do with inheriting docstrings, which I am unsure of, then I need to read up these advanced class features.

@kkoutris I am happy to collaborate with you on this issue 😄 .

[oscargus]

For what it is worth:

import inspect
import matplotlib.animation as manim
print(inspect.getdoc(manim.FFMpegFileWriter.__init__))

shows that the doc-string is correctly inherited.

Another interesting thing here is that the clickable inheritance image in https://matplotlib.org/stable/api/animation_api.html is a bit messed up for the Writer classes. Not sure if that is related.

Also note that the ImageMagickFileWriter suffers from the same problem, so if you figure out how to solve it for FFMpegFileWriter, please apply it to ImageMagickFileWriter as well.

[YetAnotherCoda]

Just for completeness, since there seems to be some refactoring of FFMpegFileWriter in progress:

• the attribute frame_size is read-only
• whereas the attribute frame_format has a setter
  This is not visible from the documentation.

To be honest, it is not obvious to me at all to set up FFMpegFileWriter.
I really appreciate your efforts.