Sprite docstrings (#2302)

* init

* animated

* base

* colored

* sprite

* collision

* spatial_hash

* sprite_list

* Remove dead links in spatial hash documentation

* Remove inactive loggers

* Misc remaining docstrings

arcade/__init__.py

@@ -20,7 +20,9 @@
 
 def configure_logging(level: int | None = None):
     """Set up basic logging.
-    :param level: The log level. Defaults to DEBUG.
+
+    Args:
+        level: The log level. Defaults to DEBUG.
     """
     import logging
 

arcade/camera/camera_2d.py

@@ -55,31 +55,31 @@ class Camera2D:
     Replacing the camera data and projection data may break controllers. Their
     contents are exposed via properties rather than directly to prevent this.
 
-    :param viewport: A 4-int tuple which defines the pixel bounds which the camera
-        will project to.
-    :param position: The 2D position of the camera in the XY plane.
-    :param up: A 2D vector which describes which direction is up
-        (defines the +Y-axis of the camera space).
-    :param zoom: A scalar value which is inversely proportional to the size of the
-        camera projection. i.e. a zoom of 2.0 halves the size of the projection,
-        doubling the perceived size of objects.
-    :param projection: A 4-float tuple which defines the world space
-                bounds which the camera projects to the viewport.
-    :param near: The near clipping plane of the camera.
-    :param far: The far clipping plane of the camera.
-    :param render_target: The FrameBuffer that the camera uses. Defaults to the screen.
-        If the framebuffer is not the default screen nothing drawn after this camera is used will
-        show up. The FrameBuffer's internal viewport is ignored.
-    :param window: The Arcade Window to bind the camera to.
-        Defaults to the currently active window.
-
-    :attributes:
-        * render_target - An optional framebuffer to activate at the same time as
-            the projection data, could be the screen, or an offscreen texture
-        * viewport - A rect which describes how the final projection should be mapped
-            from unit-space. defaults to the size of the render_target or window
-        * scissor - An optional rect which describes what pixels of the active render
-            target should be drawn to when undefined the viewport rect is used.
+    Args:
+        viewport:
+            A 4-int tuple which defines the pixel bounds which the camera will project to.
+        position:
+            The 2D position of the camera in the XY plane.
+        up:
+            A 2D vector which describes which direction is up
+            (defines the +Y-axis of the camera space).
+        zoom:
+            A scalar value which is inversely proportional to the size of the
+            camera projection. i.e. a zoom of 2.0 halves the size of the projection,
+            doubling the perceived size of objects.
+        projection:
+            A 4-float tuple which defines the world space
+            bounds which the camera projects to the viewport.
+        near:
+            The near clipping plane of the camera.
+        far:
+            The far clipping plane of the camera.
+        render_target:
+            The FrameBuffer that the camera uses. Defaults to the screen.
+            If the framebuffer is not the default screen nothing drawn after this camera
+            is used will show up. The FrameBuffer's internal viewport is ignored.
+        window:
+            The Arcade Window to bind the camera to. Defaults to the currently active window.
     """
 
     def __init__(
@@ -98,6 +98,10 @@ def __init__(
     ):
         self._window: Window = window or get_window()
         self.render_target: Framebuffer | None = render_target
+        """
+        An optional framebuffer to activate at the same time as
+        the projection data, could be the screen, or an offscreen texture
+        """
 
         # We don't want to force people to use a render target,
         # but we need to have some form of default size.
@@ -140,7 +144,16 @@ def __init__(
         )
 
         self.viewport: Rect = viewport or LRBT(0, 0, width, height)
+        """
+        A rect which describes how the final projection should be mapped
+        from unit-space. defaults to the size of the render_target or window
+        """
+
         self.scissor: Rect | None = scissor
+        """
+        An optional rect which describes what pixels of the active render
+        target should be drawn to when undefined the viewport rect is used.
+        """
 
     @classmethod
     def from_camera_data(
@@ -178,26 +191,28 @@ def from_camera_data(
           * - ``render_target``
             - Complex rendering setups
 
-        :param camera_data: A :py:class:`~arcade.camera.data.CameraData`
-            describing the position, up, forward and zoom.
-        :param projection_data:
-            A :py:class:`~arcade.camera.data.OrthographicProjectionData`
-            which describes the left, right, top, bottom, far, near
-            planes and the viewport for an orthographic projection.
-        :param render_target: A non-screen
-            :py:class:`~arcade.gl.framebuffer.Framebuffer` for this
-            camera to draw into. When specified,
-
-            * nothing will draw directly to the screen
-            * the buffer's internal viewport will be ignored
-
-        :param viewport:
-            A viewport as a :py:class:`~arcade.types.rect.Rect`.
-            This overrides any viewport the ``render_target`` may have.
-        :param scissor:
-            The OpenGL scissor box to use when drawing.
-        :param window: The Arcade Window to bind the camera to.
-            Defaults to the currently active window.
+        Args:
+            camera_data:
+                A :py:class:`~arcade.camera.data.CameraData`
+                describing the position, up, forward and zoom.
+            projection_data:
+                A :py:class:`~arcade.camera.data.OrthographicProjectionData`
+                which describes the left, right, top, bottom, far, near
+                planes and the viewport for an orthographic projection.
+            render_target:
+                A non-screen :py:class:`~arcade.gl.framebuffer.Framebuffer` for this
+                camera to draw into. When specified,
+
+                * nothing will draw directly to the screen
+                * the buffer's internal viewport will be ignored
+
+            viewport:
+                A viewport as a :py:class:`~arcade.types.rect.Rect`.
+                This overrides any viewport the ``render_target`` may have.
+            scissor:
+                The OpenGL scissor box to use when drawing.
+            window: The Arcade Window to bind the camera to.
+                Defaults to the currently active window.
         """
 
         if projection_data:

arcade/camera/data_types.py

@@ -86,8 +86,9 @@ def constrain_camera_data(data: CameraData, forward_priority: bool = False):
     Ensure that the camera data forward and up vectors are length one,
     and are perpendicular
 
-    :param data: the camera data to constrain
-    :param forward_priority: whether up or forward gets constrained
+    Args:
+        data: the camera data to constrain
+        forward_priority: whether up or forward gets constrained
     """
     forward_vec = Vec3(*data.forward).normalize()
     up_vec = Vec3(*data.up).normalize()

arcade/camera/default.py

@@ -107,7 +107,8 @@ class DefaultProjector(ViewportProjector):
     here to act as the default camera used internally by arcade. There should be
     no instance where a developer would want to use this class.
 
-    :param window: The window to bind the camera to. Defaults to the currently active window.
+    Args:
+        window: The window to bind the camera to. Defaults to the currently active window.
     """
 
     def __init__(self, *, context: ArcadeContext | None = None):

arcade/camera/grips/rotate.py

@@ -17,9 +17,12 @@ def rotate_around_forward(data: CameraData, angle: float) -> tuple[float, float,
     If that is not the center of the screen this method may appear erroneous.
     Uses arcade.camera.controllers.quaternion_rotation internally.
 
-    :param data: The camera data to modify. The data's up vector is rotated around
-        its forward vector
-    :param angle: The angle in degrees to rotate clockwise by
+    Args:
+        data:
+            The camera data to modify. The data's up vector is rotated around
+            its forward vector
+        angle:
+            The angle in degrees to rotate clockwise by
     """
     return quaternion_rotation(data.forward, data.up, angle)
 
@@ -30,9 +33,12 @@ def rotate_around_up(data: CameraData, angle: float) -> tuple[float, float, floa
     Generally only useful in 3D games.
     Uses arcade.camera.controllers.quaternion_rotation internally.
 
-    :param data: The camera data to modify. The data's forward vector is rotated
-        around its up vector
-    :param angle: The angle in degrees to rotate clockwise by
+    Args:
+        data:
+            The camera data to modify. The data's forward vector is rotated
+            around its up vector
+        angle:
+            The angle in degrees to rotate clockwise by
     """
     return quaternion_rotation(data.up, data.forward, angle)
 
@@ -45,9 +51,12 @@ def rotate_around_right(
     right vector. Generally only useful in 3D games.
     Uses arcade.camera.controllers.quaternion_rotation internally.
 
-    :param data: The camera data to modify. The data's forward vector is rotated
-        around its up vector
-    :param angle: The angle in degrees to rotate clockwise by
+    Args:
+        data:
+            The camera data to modify. The data's forward vector is rotated
+            around its up vector
+        angle:
+            The angle in degrees to rotate clockwise by
     """
     _forward = Vec3(data.forward[0], data.forward[1], data.forward[2])
     _up = Vec3(data.up[0], data.up[1], data.up[2])

arcade/camera/grips/screen_shake_2d.py

@@ -25,27 +25,21 @@ class ScreenShake2D:
     the equation rises using a inverse exponential equation, before decreasing
     using a modified smooth-step sigmoid.
 
-    Attributes:
-        max_amplitude: The largest possible world space offset.
-        falloff_duration: The length of time in seconds it takes the shaking
-                          to reach 0 after reaching the maximum. Can be set
-                          to a negative number to disable falloff.
-        shake_frequency: The number of peaks per second. Avoid making it
-                         a multiple of half the target frame-rate.
-                         (e.g. at 60 fps avoid 30, 60, 90, 120, etc.)
-
-    :param camera_data: The CameraData PoD that the controller modifies.
-                        Should not be changed once initialized.
-    :param max_amplitude: The largest possible world space offset.
-    :param falloff_time: The length of time in seconds it takes the shaking
-                        to reach 0 after reaching the maximum. Can be set
-                        to a negative number to disable falloff.
-    :param acceleration_duration: The length of time in seconds it takes the
-                                shaking to reach max amplitude. Can be set
-                                to 0.0 to start at max amplitude.
-    :param shake_frequency: The number of peaks per second. Avoid making it
-                            a multiple of half the target frame-rate.
-                            (e.g. at 60 fps avoid 30, 60, 90, 120, etc.)
+    Args:
+        camera_data:
+            The CameraData PoD that the controller modifies. Should not be
+            changed once initialized.
+        max_amplitude:
+            The largest possible world space offset.
+        falloff_time:
+            The length of time in seconds it takes the shaking to reach 0 after
+            reaching the maximum. Can be set to a negative number to disable falloff.
+        acceleration_duration:
+            The length of time in seconds it takes the shaking to reach max
+            amplitude. Can be set to 0.0 to start at max amplitude.
+        shake_frequency:
+            The number of peaks per second. Avoid making it a multiple of half
+            the target frame-rate. (e.g. at 60 fps avoid 30, 60, 90, 120, etc.)
     """
 
     def __init__(
@@ -60,8 +54,20 @@ def __init__(
         self._data: CameraData = camera_data
 
         self.max_amplitude: float = max_amplitude
+        """The largest possible world space offset."""
+
         self.falloff_duration: float = falloff_time
+        """
+        The length of time in seconds it takes the shaking to reach 0
+        after reaching the maximum.
+        """
+
         self.shake_frequency: float = shake_frequency
+        """
+        The number of peaks per second. Avoid making it a multiple of
+        half the target frame-rate.
+        """
+
         self._acceleration_duration: float = acceleration_duration
 
         self._shaking: bool = False
@@ -169,7 +175,8 @@ def _acceleration_amp(self, _t: float) -> float:
         The equation for the growing half of the amplitude equation.
         It uses 1.0001 so that at _t = 1.0 the amplitude equals 1.0.
 
-        :param _t: The scaled time. Should be between 0.0 and 1.0
+        Args:
+            _t: The scaled time. Should be between 0.0 and 1.0
         """
         return 1.0001 - 1.0001 * exp(log(0.0001 / 1.0001) * _t)
 
@@ -178,7 +185,8 @@ def _falloff_amp(self, _t: float) -> float:
         The equation for the falloff half of the amplitude equation.
         It is based on the 'smootherstep' function.
 
-        :param _t: The scaled time. Should be between 0.0 and 1.0
+        Args:
+            _t: The scaled time. Should be between 0.0 and 1.0
         """
         return 1 - _t**3 * (_t * (_t * 6.0 - 15.0) + 10.0)
 
@@ -241,9 +249,10 @@ def update(self, delta_time: float) -> None:
         Does not actually set the camera position.
         Should not be called more than once an update cycle.
 
-        :param delta_time: the length of time in seconds between update calls.
-                        Generally pass in the delta_time provided by the
-                        arcade.Window's on_update method.
+        Args:
+            delta_time:
+                the length of time in seconds between update calls. Generally pass
+                in the delta_time provided by the arcade.Window's on_update method.
         """
         if not self._shaking:
             return

arcade/camera/orthographic.py

@@ -42,10 +42,14 @@ class OrthographicProjector(Projector):
     Initialize a Projector which produces an orthographic projection matrix using
     a CameraData and PerspectiveProjectionData PoDs.
 
-    :param window: The window to bind the camera to. Defaults to the currently active camera.
-    :param view: The CameraData PoD. contains the viewport, position, up, forward, and zoom.
-    :param projection: The OrthographicProjectionData PoD.
-                contains the left, right, bottom top, near, and far planes.
+    Args:
+        window:
+            The window to bind the camera to. Defaults to the currently active camera.
+        view:
+            The CameraData PoD. contains the viewport, position, up, forward, and zoom.
+        projection:
+            The OrthographicProjectionData PoD.
+            contains the left, right, bottom top, near, and far planes.
     """
 
     def __init__(

arcade/camera/perspective.py

@@ -43,10 +43,14 @@ class PerspectiveProjector(Projector):
     Initialize a Projector which produces a perspective projection matrix using
     a CameraData and PerspectiveProjectionData PoDs.
 
-    :param window: The window to bind the camera to. Defaults to the currently active camera.
-    :param view: The CameraData PoD. contains the viewport, position, up, forward, and zoom.
-    :param projection: The PerspectiveProjectionData PoD.
-                contains the field of view, aspect ratio, and then near and far planes.
+    Args:
+        window:
+            The window to bind the camera to. Defaults to the currently active camera.
+        view:
+            The CameraData PoD. contains the viewport, position, up, forward, and zoom.
+        projection:
+            The PerspectiveProjectionData PoD. contains the field of view, aspect ratio,
+            and then near and far planes.
     """
 
     def __init__(