Improve docstring for interpolate method in Mobject class

manim/animation/transform.py

@@ -123,6 +123,10 @@ def make_arc_path(start, end, arc_angle):
 
                 self.play(*anims, run_time=2)
                 self.wait()
+
+    See also
+    --------
+    :class:`~.ReplacementTransform`, :meth:`~.Mobject.interpolate`, :meth:`~.Mobject.align_data`
     """
 
     def __init__(

manim/mobject/mobject.py

@@ -2840,22 +2840,64 @@ def interpolate(
         """Turns this :class:`~.Mobject` into an interpolation between ``mobject1``
         and ``mobject2``.
 
+        The interpolation is applied to the points and color of the mobject.
+
+        Parameters
+        ----------
+        mobject1
+            The starting Mobject.
+        mobject2
+            The target Mobject.
+        alpha
+            Interpolation factor between 0 (at ``mobject1``) and 1 (at ``mobject2``).
+        path_func
+            The function defining the interpolation path. Defaults to a straight path.
+
+        Returns
+        -------
+        :class:`Mobject`
+            ``self``
+
+
+        .. note::
+
+            - Both mobjects must have the same number of points. If not, this will raise an error.
+              Use :meth:`~.VMobject.align_points` to match point counts beforehand if needed.
+            - This method is used internally by the :class:`~.Transform` animation
+              to interpolate between two mobjects during a transformation.
+
         Examples
         --------
 
-        .. manim:: DotInterpolation
+        .. manim:: InterpolateExample
             :save_last_frame:
 
-            class DotInterpolation(Scene):
+            class InterpolateExample(Scene):
                 def construct(self):
-                    dotR = Dot(color=DARK_GREY)
-                    dotR.shift(2 * RIGHT)
-                    dotL = Dot(color=WHITE)
-                    dotL.shift(2 * LEFT)
-
-                    dotMiddle = VMobject().interpolate(dotL, dotR, alpha=0.3)
+                    # No need for point alignment:
+                    dotL = Dot(color=DARK_GREY).to_edge(LEFT)
+                    dotR = Dot(color=YELLOW).scale(10).to_edge(RIGHT)
+                    dotMid1 = VMobject().interpolate(dotL, dotR, alpha=0.1)
+                    dotMid2 = VMobject().interpolate(dotL, dotR, alpha=0.25)
+                    dotMid3 = VMobject().interpolate(dotL, dotR, alpha=0.5)
+                    dotMid4 = VMobject().interpolate(dotL, dotR, alpha=0.75)
+                    dots = VGroup(dotL, dotR, dotMid1, dotMid2, dotMid3, dotMid4)
+
+                    # Needs point alignment:
+                    line = Line(ORIGIN, UP).to_edge(LEFT)
+                    sq = Square(color=RED, fill_opacity=1, stroke_color=BLUE).to_edge(RIGHT)
+                    line.align_points(sq)
+                    mid1 = VMobject().interpolate(line, sq, alpha=0.1)
+                    mid2 = VMobject().interpolate(line, sq, alpha=0.25)
+                    mid3 = VMobject().interpolate(line, sq, alpha=0.5)
+                    mid4 = VMobject().interpolate(line, sq, alpha=0.75)
+                    linesquares = VGroup(line, sq, mid1, mid2, mid3, mid4)
+
+                    self.add(VGroup(dots, linesquares).arrange(DOWN, buff=1))
+        See also
+        --------
+        :class:`~.Transform`, :meth:`~.VMobject.align_points`, :meth:`~.VMobject.interpolate_color`
 
-                    self.add(dotL, dotR, dotMiddle)
         """
         self.points = path_func(mobject1.points, mobject2.points, alpha)
         self.interpolate_color(mobject1, mobject2, alpha)

manim/mobject/types/vectorized_mobject.py

@@ -1720,6 +1720,10 @@ def align_points(self, vmobject: VMobject) -> Self:
         -------
         :class:`VMobject`
            ``self``
+
+        See also
+        --------
+        :meth:`~.Mobject.interpolate`, :meth:`~.Mobject.align_data`
         """
         self.align_rgbas(vmobject)
         # TODO: This shortcut can be a bit over eager. What if they have the same length, but different subpath lengths?