Rate function usage for custom animations in the docs is unclear/misleading

[pyrodynamic]

Description of bug / unexpected behavior

In the Manim’s building blocks > Creating a custom animation section of the documentation, it is not made clear that the rate function must be explicitly called on the alpha parameter in interpolate_mobject() in order to allow for the usage of the rate_func parameter to work as intended.

From that page:

So, you just have to manipulate self.mobject inside Animation according to the alpha value in its interpolate_mobject method. Then you get all the benefits of Animation such as playing it for different run times or using different rate functions.
[...]
The only thing that you need to do is to define how you want it to look at every step of the animation. Manim provides you with the alpha value in the interpolate_mobject() method based on frame rate of video, rate function, and run time of animation played.

The code given:

from manim import *

class Count(Animation):
    def __init__(self, number: DecimalNumber, start: float, end: float, **kwargs) -> None:
        # Pass number as the mobject of the animation
        super().__init__(number,  **kwargs)
        # Set start and end
        self.start = start
        self.end = end

    def interpolate_mobject(self, alpha: float) -> None:
        # Set value of DecimalNumber according to alpha
        value = self.start + (alpha * (self.end - self.start))
        self.mobject.set_value(value)


class CountingScene(Scene):
    def construct(self):
        # Create Decimal Number and add it to scene
        number = DecimalNumber().set_color(WHITE).scale(5)
        # Add an updater to keep the DecimalNumber centered as its value changes
        number.add_updater(lambda number: number.move_to(ORIGIN))

        self.add(number)

        self.wait()

        # Play the Count Animation to count from 0 to 100 in 4 seconds
        self.play(Count(number, 0, 100), run_time=4, rate_func=linear)

        self.wait()

This excerpt (along with the code given after it) gives the impression that the alpha parameter is already adjusted for the rate function (if one is specified) and can be used directly, which is NOT the case. For example, a rate_func is specified as an argument to play() in the code above when in this case the rate_func parameter would have no effect whatsoever. In the current manim version, if one wishes to support different rate functions, it is required to call self.rate_func() on alpha instead of using alpha directly.

Expected behavior

The documentation should be more descriptive and provide a better code snippet with the proper implementation of rate functions for custom animations.

How to reproduce the issue

This is a page from the official documentation.

[behackl]

Thanks for the report. Updating this particular page would be a good issue for a first contribution; might also be related to #3157

[pedropxoto]

Hi, is there a reason why this issue is still open, given that PR #4173 was proposed to address it?

[melodysium]

@pedropxoto the author of that PR seemingly self-closed without any reason I see, so I believe the issue still stands.

i've been tracking this issue to maybe pick it up myself some weekend, but I'm not planning on it, and i'm certainly not blocking others from addressing it.