Improved readability, grammar, as well as added docstrings for consistency (#4267)

* Improve MappingCamera, MovingCamera, Rotation, CliColors, and _init_.py readability and docstrings

* Readibility and docsstrings

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

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

* Apply suggestion from @behackl

---------

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

Author: 3 people

manim/_config/__init__.py

@@ -23,10 +23,9 @@
 
 parser = make_config_parser()
 
-# The logger can be accessed from anywhere as manim.logger, or as
-# logging.getLogger("manim").  The console must be accessed as manim.console.
-# Throughout the codebase, use manim.console.print() instead of print().
-# Use error_console to print errors so that it outputs to stderr.
+# Logger usage: accessible globally as `manim.logger` or via `logging.getLogger("manim")`.
+# For printing, use `manim.console.print()` instead of the built-in `print()`.
+# For error output, use `error_console`, which prints to stderr.
 logger, console, error_console = make_logger(
     parser["logger"],
     parser["CLI"]["verbosity"],
@@ -45,7 +44,7 @@
 # This has to go here because it needs access to this module's config
 @contextmanager
 def tempconfig(temp: ManimConfig | dict[str, Any]) -> Generator[None, None, None]:
-    """Context manager that temporarily modifies the global ``config`` object.
+    """Temporarily modifies the global ``config`` object using a context manager.
 
     Inside the ``with`` statement, the modified config will be used.  After
     context manager exits, the config will be restored to its original state.

manim/_config/cli_colors.py

@@ -1,3 +1,9 @@
+"""Parses CLI context settings from the configuration file and returns a Cloup Context settings dictionary.
+
+This module reads configuration values for help formatting, theme styles, and alignment options
+used when rendering command-line interfaces in Manim.
+"""
+
 from __future__ import annotations
 
 import configparser
@@ -28,6 +34,7 @@ def parse_cli_ctx(parser: configparser.SectionProxy) -> dict[str, Any]:
         "col2",
         "epilog",
     }
+    # Extract and apply any style-related keys defined in the config section.
     for k, v in parser.items():
         if k in theme_keys and v:
             theme_settings.update({k: Style(v)})

manim/camera/mapping_camera.py

@@ -1,4 +1,4 @@
-"""A camera that allows mapping between objects."""
+"""A camera module that supports spatial mapping between objects for distortion effects."""
 
 from __future__ import annotations
 
@@ -17,8 +17,16 @@
 
 
 class MappingCamera(Camera):
-    """Camera object that allows mapping
-    between objects.
+    """Parameters
+    ----------
+    mapping_func : callable
+        Function to map 3D points to new 3D points (identity by default).
+    min_num_curves : int
+        Minimum number of curves for VMobjects to avoid visual glitches.
+    allow_object_intrusion : bool
+        If True, modifies original mobjects; else works on copies.
+    kwargs : dict
+        Additional arguments passed to Camera base class.
     """
 
     def __init__(
@@ -34,12 +42,18 @@ def __init__(
         super().__init__(**kwargs)
 
     def points_to_pixel_coords(self, mobject, points):
+        # Map points with custom function before converting to pixels
         return super().points_to_pixel_coords(
             mobject,
             np.apply_along_axis(self.mapping_func, 1, points),
         )
 
     def capture_mobjects(self, mobjects, **kwargs):
+        """Capture mobjects for rendering after applying the spatial mapping.
+
+        Copies mobjects unless intrusion is allowed, and ensures
+        vector objects have enough curves for smooth distortion.
+        """
         mobjects = self.get_mobjects_to_display(mobjects, **kwargs)
         if self.allow_object_intrusion:
             mobject_copies = mobjects
@@ -67,6 +81,13 @@ def capture_mobjects(self, mobjects, **kwargs):
 
 # TODO, the classes below should likely be deleted
 class OldMultiCamera(Camera):
+    """Parameters
+    ----------
+    cameras_with_start_positions : tuple
+        Tuples of (Camera, (start_y, start_x)) indicating camera and
+        its pixel offset on the final frame.
+    """
+
     def __init__(self, *cameras_with_start_positions, **kwargs):
         self.shifted_cameras = [
             DictAsObject(
@@ -125,6 +146,15 @@ def init_background(self):
 
 
 class SplitScreenCamera(OldMultiCamera):
+    """Initializes a split screen camera setup with two side-by-side cameras.
+
+    Parameters
+    ----------
+    left_camera : Camera
+    right_camera : Camera
+    kwargs : dict
+    """
+
     def __init__(self, left_camera, right_camera, **kwargs):
         Camera.__init__(self, **kwargs)  # to set attributes such as pixel_width
         self.left_camera = left_camera

manim/camera/moving_camera.py

@@ -1,9 +1,8 @@
-"""A camera able to move through a scene.
+"""Defines the MovingCamera class, a camera that can pan and zoom through a scene.
 
 .. SEEALSO::
 
     :mod:`.moving_camera_scene`
-
 """
 
 from __future__ import annotations
@@ -21,13 +20,13 @@
 
 
 class MovingCamera(Camera):
-    """
-    Stays in line with the height, width and position of it's 'frame', which is a Rectangle
+    """A camera that follows and matches the size and position of its 'frame', a Rectangle (or similar Mobject).
+
+    The frame defines the region of space the camera displays and can move or resize dynamically.
 
     .. SEEALSO::
 
         :class:`.MovingCameraScene`
-
     """
 
     def __init__(
@@ -38,8 +37,7 @@ def __init__(
         default_frame_stroke_width=0,
         **kwargs,
     ):
-        """
-        Frame is a Mobject, (should almost certainly be a rectangle)
+        """Frame is a Mobject, (should almost certainly be a rectangle)
         determining which region of space the camera displays
         """
         self.fixed_dimension = fixed_dimension
@@ -132,16 +130,14 @@ def capture_mobjects(self, mobjects, **kwargs):
     # context used for updating should be regenerated
     # at each frame.  So no caching.
     def get_cached_cairo_context(self, pixel_array):
-        """
-        Since the frame can be moving around, the cairo
+        """Since the frame can be moving around, the cairo
         context used for updating should be regenerated
         at each frame.  So no caching.
         """
         return None
 
     def cache_cairo_context(self, pixel_array, ctx):
-        """
-        Since the frame can be moving around, the cairo
+        """Since the frame can be moving around, the cairo
         context used for updating should be regenerated
         at each frame.  So no caching.
         """
@@ -159,8 +155,7 @@ def cache_cairo_context(self, pixel_array, ctx):
     #     self.resize_frame_shape(fixed_dimension=self.fixed_dimension)
 
     def get_mobjects_indicating_movement(self):
-        """
-        Returns all mobjects whose movement implies that the camera
+        """Returns all mobjects whose movement implies that the camera
         should think of all other mobjects on the screen as moving
 
         Returns