Docs (#347)

* add some module docstrings

* add some breathing room in the generated autosummaries

* edit template so it generates cleaner output

* document add and remove

* document new conf.py option

* updates from code review

Co-authored-by: Pg Biel <[email protected]>
Co-authored-by: Aathish Sivasubrahmanian <[email protected]>
Co-authored-by: Naveen M K <[email protected]>

Author: 4 people

docs/source/_static/custom.css

@@ -0,0 +1,3 @@
+td {
+    padding: 0px 10px 0px 10px;
+}

docs/source/_templates/autosummary/class.rst

@@ -5,25 +5,25 @@
 .. autoclass:: {{ objname }}
 
    {% block methods %}
-   {% if methods %}
+   {%- if methods %}
    .. rubric:: {{ _('Methods') }}
 
    .. autosummary::
       :nosignatures:
       :toctree: .
       {% for item in methods if item != '__init__' and item not in inherited_members %}
-        ~{{ name }}.{{ item }}
+      ~{{ name }}.{{ item }}
       {%- endfor %}
-   {% endif %}
-   {% endblock %}
+   {%- endif %}
+   {%- endblock %}
 
    {% block attributes %}
-   {% if attributes %}
+   {%- if attributes %}
    .. rubric:: {{ _('Attributes') }}
 
    .. autosummary::
-   {% for item in attributes %}
-      ~{{ name }}.{{ item }}
-   {%- endfor %}
-   {% endif %}
+     {% for item in attributes %}
+     ~{{ name }}.{{ item }}
+     {%- endfor %}
+   {%- endif %}
    {% endblock %}

docs/source/conf.py

@@ -66,8 +66,10 @@
 # Register the theme as an extension to generate a sitemap.xml
 extensions.append("guzzle_sphinx_theme")
 
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
+
+# This specifies any additional css files that will override the theme's
+html_css_files = ['custom.css']

manim/animation/animation.py

@@ -1,3 +1,4 @@
+"""Animate mobjects."""
 from copy import deepcopy
 
 import numpy as np

manim/animation/composition.py

@@ -1,3 +1,4 @@
+"""Tools for displaying multiple animations at once."""
 import numpy as np
 
 from ..animation.animation import Animation

manim/animation/creation.py

@@ -1,3 +1,4 @@
+"""Animate the display or removal of a mobject from a scene."""
 from ..animation.animation import Animation
 from ..animation.composition import Succession
 from ..mobject.types.vectorized_mobject import VMobject
@@ -131,7 +132,7 @@ def update_submobject_list(self, index):
 
 class AddTextLetterByLetter(ShowIncreasingSubsets):
     """
-        Add a Text Object letter by letter on the scene. Use time_per_char to change frequency of appearance of the letters. 
+        Add a Text Object letter by letter on the scene. Use time_per_char to change frequency of appearance of the letters.
     """
 
     CONFIG = {

manim/animation/fading.py

@@ -1,3 +1,4 @@
+"""Fading in and out of view."""
 from ..animation.animation import Animation
 from ..animation.animation import DEFAULT_ANIMATION_LAG_RATIO
 from ..animation.transform import Transform

manim/camera/camera.py

@@ -1,3 +1,4 @@
+"A Camera converts the mobjects contained in a Scene into an array of pixels"
 from functools import reduce
 import itertools as it
 import operator as op

manim/mobject/geometry.py

@@ -1,10 +1,4 @@
-"""
-geometry.py
------------
-
-Classes implementing geometric objects, mostly derived from MObject.
-
-"""
+"""Mobjects that are simple geometric shapes."""
 import warnings
 import numpy as np
 import math

manim/mobject/mobject.py

@@ -1,6 +1,4 @@
-"""
-MObject: Base classes for all mathematical objects.
-"""
+"""Base classes for objects that can be displayed."""
 from functools import reduce
 import copy
 import itertools as it
@@ -30,8 +28,13 @@
 
 
 class Mobject(Container):
-    """
-    Mathematical Object
+    """Mathematical Object: base class for objects that can be displayed on screen.
+
+    Attributes
+    ----------
+    submobjects : :class:`list`
+        The contained objects.
+
     """
 
     CONFIG = {
@@ -69,6 +72,37 @@ def generate_points(self):
         pass
 
     def add(self, *mobjects):
+        """Add mobjects as submobjects.
+
+        The mobjects are added to self.submobjects.
+
+        Parameters
+        ----------
+        mobjects : List[:class:`Mobject`]
+            The mobjects to add.
+
+        Returns
+        -------
+        :class:`Mobject`
+            :code:`self`
+
+        Raises
+        ------
+        :class:`ValueError`
+            When a mobject tries to add itself.
+
+        Notes
+        -----
+        A mobject cannot contain itself, and it cannot contain a submobject
+        more than once.  If the parent mobject is displayed, the newly-added
+        submobjects will also be displayed (i.e. they are automatically added
+        to the parent Scene).
+
+        See Also
+        --------
+        :meth:`~Mobject.remove`
+
+        """
         if self in mobjects:
             raise ValueError("Mobject cannot contain self")
         self.submobjects = list_update(self.submobjects, mobjects)
@@ -80,6 +114,25 @@ def add_to_back(self, *mobjects):
         return self
 
     def remove(self, *mobjects):
+        """Remove submobjects.
+
+        The mobjects are removed from self.submobjects, if they exist.
+
+        Parameters
+        ----------
+        mobjects : List[:class:`Mobject`]
+            The mobjects to remove.
+
+        Returns
+        -------
+        :class:`Mobject`
+            :code:`self`
+
+        See Also
+        --------
+        :meth:`~Mobject.add`
+
+        """
         for mobject in mobjects:
             if mobject in self.submobjects:
                 self.submobjects.remove(mobject)
@@ -1097,6 +1150,8 @@ def set_z_index_by_z_coordinate(self):
 
 
 class Group(Mobject):
+    """Groups together multiple Mobjects."""
+
     def __init__(self, *mobjects, **kwargs):
         if not all([isinstance(m, Mobject) for m in mobjects]):
             raise Exception("All submobjects must be of type Mobject")