Add examples to animation creation (3b1b#820)

* added creation animation

* added further animation

* added further animation + docstring template

* added further examples

* black

* one more update

* one more update

* one more update

* one more update

* one more update become

* hope that this will fix the build

* Apply suggestions from code review

Co-authored-by: Benjamin Hackl <devel@benjamin-hackl.at>
Co-authored-by: Leo Torres <dleonardotn@gmail.com>

* updated templates

* small fix

* tests

* Apply suggestions from code review

Co-authored-by: Benjamin Hackl <devel@benjamin-hackl.at>

* Update README.md

* merged master and typo in README.md

Co-authored-by: Benjamin Hackl <devel@benjamin-hackl.at>
Co-authored-by: Leo Torres <dleonardotn@gmail.com>

README.md

@@ -32,7 +32,7 @@ Manim is an animation engine for explanatory math videos. It's used to create pr
 
 ## Installation
 
-Manim requires a few dependencies that must be installed prior to using it. Please visit the [documentation](https://docs.manim.community/en/latest/installation.html) and follow the appropriate instructions for your operating system.
+Manim requires a few dependencies that must be installed prior to using it. Please visit the [Documentation](https://docs.manim.community/en/latest/installation.html) and follow the appropriate instructions for your operating system.
 
 Once the dependencies have been installed, run the following in a terminal window:
 

manim/animation/creation.py

@@ -153,6 +153,14 @@ def _get_bounds(self, alpha: float) -> typing.Tuple[int, float]:
 class Uncreate(ShowCreation):
     """Like :class:`ShowCreation` but in reverse.
 
+    Examples
+    --------
+    .. manim:: ShowUncreate
+
+        class ShowUncreate(Scene):
+            def construct(self):
+                self.play(Uncreate(Square()))
+
     See Also
     --------
     :class:`ShowCreation`
@@ -172,7 +180,16 @@ def __init__(
 
 
 class DrawBorderThenFill(Animation):
-    """Draw the border first and then show the fill."""
+    """Draw the border first and then show the fill.
+
+    Examples
+    --------
+    .. manim:: ShowDrawBorderThenFill
+
+        class ShowDrawBorderThenFill(Scene):
+            def construct(self):
+                self.play(DrawBorderThenFill(Square(fill_opacity=1, fill_color=ORANGE)))
+    """
 
     def __init__(
         self,
@@ -230,7 +247,16 @@ def interpolate_submobject(
 
 
 class Write(DrawBorderThenFill):
-    """Simulate hand-writing a :class:`~.Text` or hand-drawing a :class:`~.VMobject`."""
+    """Simulate hand-writing a :class:`~.Text` or hand-drawing a :class:`~.VMobject`.
+
+    Examples
+    --------
+    .. manim:: ShowWrite
+
+        class ShowWrite(Scene):
+            def construct(self):
+                self.play(Write(Text("Hello").scale(3)))
+    """
 
     def __init__(
         self,
@@ -263,7 +289,20 @@ def _set_default_config_from_length(self, vmobject: VMobject) -> None:
 
 
 class ShowIncreasingSubsets(Animation):
-    """Show one submobject at a time, leaving all previous ones displayed on screen."""
+    """Show one submobject at a time, leaving all previous ones displayed on screen.
+
+    Examples
+    --------
+
+    .. manim:: ShowIncreasingSubsetsScene
+
+        class ShowIncreasingSubsetsScene(Scene):
+            def construct(self):
+                p = VGroup(Dot(), Square(), Triangle())
+                self.add(p)
+                self.play(ShowIncreasingSubsets(p))
+                self.wait()
+    """
 
     def __init__(
         self,
@@ -295,6 +334,10 @@ class AddTextLetterByLetter(ShowIncreasingSubsets):
     time_per_char : :class:`float`
         Frequency of appearance of the letters.
 
+    .. tip::
+
+        This is currently only possible for class:`~.Text` and not for class:`~.MathTex`
+
     """
 
     def __init__(
@@ -344,7 +387,7 @@ def update_submobject_list(self, index: int) -> None:
 
 # TODO, this is broken...
 class AddTextWordByWord(Succession):
-    """Show a :class:`~.Text` word by word on the scene."""
+    """Show a :class:`~.Text` word by word on the scene. Note: currently broken."""
 
     def __init__(
         self,

manim/animation/indication.py

@@ -174,8 +174,9 @@ class ShowPassingFlash(ShowPartial):
 
         class ShowPassingFlashScene(Scene):
             def construct(self):
-                self.play(ShowPassingFlash(Square()))
-
+                p = RegularPolygon(5)
+                self.add(p)
+                self.play(ShowPassingFlash(p.copy().set_color(YELLOW)))
 
     See Also
     --------

manim/mobject/mobject.py

@@ -1229,8 +1229,21 @@ def pointwise_become_partial(self, mobject, a, b):
 
     def become(self, mobject, copy_submobjects=True):
         """
-        Edit points, colors and submobjects to be idential
+        Edit points, colors and submobjects to be identical
         to another mobject
+
+        Examples
+        --------
+        .. manim:: BecomeScene
+
+            class BecomeScene(Scene):
+                def construct(self):
+                    circ= Circle(fill_color=RED)
+                    square = Square(fill_color=BLUE)
+                    self.add(circ)
+                    self.wait(0.5)
+                    circ.become(square)
+                    self.wait(0.5)
         """
         self.align_data(mobject)
         for sm1, sm2 in zip(self.get_family(), mobject.get_family()):

scripts/template_docsting_with_example.py

@@ -0,0 +1,79 @@
+# see more documentation guidelines online here: https://github.com/ManimCommunity/manim/wiki/Documentation-guidelines-(WIP)
+
+
+class SomeClass:
+    """A one line description of the Class.
+
+    A short paragraph providing more details.
+
+    Deprecation warning
+
+    Extended Summary
+
+    Parameters
+    ----------
+    scale_factor : :class:`float`
+        The factor used for scaling.
+
+    Returns
+    -------
+    :class:`~.VMobject`
+        Returns the modified :class:`~.VMobject`.
+
+    Tests
+    -----
+
+    Yields
+    -------
+
+    Receives
+    ----------
+
+    Other Parameters
+    -----------------
+
+    Raises
+    ------
+    :class:`TypeError`
+        If one element of the list is not an instance of VMobject
+
+    Warns
+    -----
+
+    Warnings
+    --------
+
+    Notes
+    -----
+
+    Examples
+    --------
+    .. manim:: AddTextLetterByLetterScene
+        :save_last_frame:
+
+        class AddTextLetterByLetterScene(Scene):
+            def construct(self):
+                t = Text("Hello World word by word")
+                self.play(AddTextWordByWord(t))
+
+
+
+    See Also
+    --------
+    :class:`ShowCreation`, :class:`~.ShowPassingFlash`
+
+    References
+    ----------
+
+
+    Other useful directives:
+
+    .. tip::
+
+        This is currently only possible for class:`~.Text` and not for class:`~.MathTex`.
+
+    .. note::
+
+        This is something to note.
+
+    """