Further docstrings and examples for :class:~.Mobject (#1232)

* added further docsting to mobject.py

* added colour

* removed np.random

* invert docsting

* black + get numpy back

* match docstrings

* Update manim/mobject/mobject.py

* Update manim/mobject/mobject.py

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update manim/mobject/mobject.py

Co-authored-by: Jason Villanueva <[email protected]>

* Apply suggestions from code review

Co-authored-by: Jason Villanueva <[email protected]>

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Jason Villanueva <[email protected]>

Author: 3 people

manim/mobject/mobject.py

@@ -386,7 +386,7 @@ def add_to_back(self, *mobjects: "Mobject") -> "Mobject":
         return self
 
     def remove(self, *mobjects: "Mobject") -> "Mobject":
-        """Remove submobjects.
+        """Remove :attr:`submobjects`.
 
         The mobjects are removed from :attr:`submobjects`, if they exist.
 
@@ -635,12 +635,13 @@ def show(self, camera=None):
         self.get_image(camera=camera).show()
 
     def save_image(self, name=None):
+        """Saves an image of only this :class:`Mobject` at its position to a png file."""
         self.get_image().save(
             Path(config.get_dir("video_dir")).joinpath((name or str(self)) + ".png")
         )
 
     def copy(self) -> "Mobject":
-        """Create and return an identical copy of the Mobject including all submobjects.
+        """Create and return an identical copy of the :class:`Mobject` including all :attr:`submobjects`.
 
         Returns
         -------
@@ -1649,6 +1650,7 @@ def fade(self, darkness=0.5, family=True):
         return self
 
     def get_color(self):
+        """Returns the color of the :class:`~.Mobject`"""
         return self.color
 
     ##
@@ -1879,12 +1881,15 @@ def match_coord(self, mobject: "Mobject", dim, direction=ORIGIN):
         )
 
     def match_x(self, mobject: "Mobject", direction=ORIGIN):
+        """Match x coord. to the x coord. of another :class:`~.Mobject`."""
         return self.match_coord(mobject, 0, direction)
 
-    def match_y(self, mobject: "Mobject", direction=ORIGIN):
+    def Match_y(self, mobject: "Mobject", direction=ORIGIN):
+        """Match y coord. to the x coord. of another :class:`~.Mobject`."""
         return self.match_coord(mobject, 1, direction)
 
     def match_z(self, mobject: "Mobject", direction=ORIGIN):
+        """Match z coord. to the x coord. of another :class:`~.Mobject`."""
         return self.match_coord(mobject, 2, direction)
 
     def align_to(
@@ -1954,7 +1959,7 @@ def arrange(
         center=True,
         **kwargs,
     ):
-        """Sorts mobjects next to each other on screen.
+        """Sorts :class:`~.Mobject` next to each other on screen.
 
         Examples
         --------
@@ -2011,19 +2016,68 @@ def shuffle(self, recursive=False):
         random.shuffle(self.submobjects)
 
     def invert(self, recursive=False):
+        """Inverts the list of :attr:`submobjects`.
+
+        Examples
+        --------
+
+        .. manim:: InvertSumobjectsExample
+
+            class InvertSumobjectsExample(Scene):
+                def construct(self):
+                    s= VGroup(*[Dot().shift(i*0.1*RIGHT) for i in range(-20,20)])
+                    s2= s.copy()
+                    s2.invert()
+                    s2.shift(DOWN)
+                    self.play(Write(s), Write(s2))
+        """
         if recursive:
             for submob in self.submobjects:
                 submob.invert(recursive=True)
         list.reverse(self.submobjects)
 
     # Just here to keep from breaking old scenes.
     def arrange_submobjects(self, *args, **kwargs):
+        """Arrange the position of :attr:`submobjects` with a small buffer.
+
+        Examples
+        --------
+
+        .. manim:: ArrangeSumobjectsExample
+            :save_last_frame:
+
+            class ArrangeSumobjectsExample(Scene):
+                def construct(self):
+                    s= VGroup(*[Dot().shift(i*0.1*RIGHT*np.random.uniform(-1,1)+UP*np.random.uniform(-1,1)) for i in range(0,15)])
+                    s.shift(UP).set_color(BLUE)
+                    s2= s.copy().set_color(RED)
+                    s2.arrange_submobjects()
+                    s2.shift(DOWN)
+                    self.add(s,s2)
+
+        """
         return self.arrange(*args, **kwargs)
 
     def sort_submobjects(self, *args, **kwargs):
+        """Sort the :attr:`submobjects`"""
         return self.sort(*args, **kwargs)
 
     def shuffle_submobjects(self, *args, **kwargs):
+        """Shuffles the order of :attr:`submobjects`
+
+        Examples
+        --------
+
+        .. manim:: SuffleSumobjectsExample
+
+            class SuffleSumobjectsExample(Scene):
+                def construct(self):
+                    s= VGroup(*[Dot().shift(i*0.1*RIGHT) for i in range(-20,20)])
+                    s2= s.copy()
+                    s2.shuffle_submobjects()
+                    s2.shift(DOWN)
+                    self.play(Write(s), Write(s2))
+        """
         return self.shuffle(*args, **kwargs)
 
     # Alignment