Touch-up top-level docstrings for Sprite & BasicSprite

arcade/sprite/base.py

@@ -16,6 +16,15 @@
 class BasicSprite:
     """
     The absolute minimum needed for a sprite.
+
+    It does not support features like rotation or changing the hitbox
+    after creation. For more built-in features, please see
+    :py:class:`~arcade.Sprite`.
+
+    :param texture: The texture data to use for this sprite.
+    :param scale: The scaling factor for drawing the texture.
+    :param center_x: Location of the sprite along the X axis in pixels.
+    :param center_y: Location of the sprite along the Y axis in pixels.
     """
 
     __slots__ = (

arcade/sprite/sprite.py

@@ -17,14 +17,26 @@
 
 class Sprite(BasicSprite, PymunkMixin):
     """
-    Class that represents a 'sprite' on-screen. Most games center around sprites.
-    For examples on how to use this class, see:
-    https://api.arcade.academy/en/latest/examples/index.html#sprites
-
-    :param str path_or_texture: Path to the image file, or a texture object.
-    :param float center_x: Location of the sprite
-    :param float center_y: Location of the sprite
-    :param float scale: Scale the image up or down. Scale of 1.0 is none.
+    Sprites are used to render image data to the screen & perform collisions.
+
+    Most games center around sprites. They are most frequently used as follows:
+
+    1. Create ``Sprite`` instances from image data
+    2. Add the sprites to a :py:class:`~arcade.SpriteList` instance
+    3. Call :py:meth:`SpriteList.draw() <arcade.SpriteList.draw>` on the
+       instance inside your ``on_draw`` method.
+
+    For runnable examples of how to do this, please see arcade's
+    :ref:`built-in Sprite examples <sprites>`.
+
+    .. tip:: Advanced users should see :py:class:`~arcade.BasicSprite`
+
+             It uses fewer resources at the cost of having fewer features.
+
+    :param str path_or_texture: Path to an image file, or a texture object.
+    :param float center_x: Location of the sprite in pixels.
+    :param float center_y: Location of the sprite in pixels.
+    :param float scale: Show the image at this many times its original size.
     :param float angle: The initial rotation of the sprite in degrees
     """