Reduce excessive output when building docs + fix missing docstring warnings (#2630)

* All output from docs build should use logging

* Make warning the default log level

* Missing docstring in pymunk_physics_engine

* Missing docstrings

Author: einarf

arcade/camera/data_types.py

@@ -427,7 +427,16 @@ def use(self) -> None:
         ...
 
     @contextmanager
-    def activate(self) -> Generator[Self, None, None]: ...
+    def activate(self) -> Generator[Self, None, None]:
+        """
+        Activate this projector for rendering.
+
+        This is a context manager and should be used with a ``with`` statement::
+
+            with projector.activate():
+                # Render with this projector
+        """
+        ...
 
     def project(self, world_coordinate: Point) -> Vec2:
         """

arcade/clock.py

@@ -95,6 +95,9 @@ def ticks_since(self, tick: int) -> int:
 
     @property
     def max_deltatime(self) -> float | None:
+        """
+        The maximum deltatime that the clock will allow. If a large dt is passed into
+        """
         return self._max_deltatime
 
     @property

arcade/easing.py

@@ -23,6 +23,9 @@ class EasingData:
     ease_function: Callable
 
     def reset(self) -> None:
+        """
+        Reset the easing data to its initial state.
+        """
         self.cur_period = self.start_period
 
 

arcade/future/background/background_texture.py

@@ -15,6 +15,12 @@ class BackgroundTexture:
 
     The Mat3s define the scaling, rotation, and translation of the pixel data in the texture.
     see background_fs.glsl in resources/shaders for an implementation of this.
+
+    Args:
+        texture: The texture to use as the background.
+        offset: The offset of the texture in pixels.
+        scale: The scale of the texture.
+        angle: The angle of the texture in radians.
     """
 
     def __init__(
@@ -41,6 +47,10 @@ def pixel_transform(self):
 
     @property
     def scale(self) -> float:
+        """
+        Get or set the scale of the texture. This is a multiplier on the size of the texture.
+        Default value is ``1.0``.
+        """
         return self._scale
 
     @scale.setter
@@ -50,6 +60,10 @@ def scale(self, value: float):
 
     @property
     def angle(self) -> float:
+        """
+        Get or set the angle of the texture. This is a rotation in radians.
+        Default value is ``0.0``.
+        """
         return self._angle
 
     @angle.setter
@@ -59,6 +73,10 @@ def angle(self, value: float):
 
     @property
     def offset(self) -> tuple[float, float]:
+        """
+        Get or set the offset of the texture. This is a translation in pixels.
+        Default value is ``(0.0, 0.0)``.
+        """
         return self._offset
 
     @offset.setter
@@ -134,6 +152,17 @@ def render_target(
         color_attachments: list[gl.Texture2D] | None = None,
         depth_attachment: gl.Texture2D | None = None,
     ) -> gl.Framebuffer:
+        """
+        Create a framebuffer for the texture.
+
+        This framebuffer is used to render to the texture. The framebuffer is created with the
+        texture as the color attachment.
+
+        Args:
+            context: The context to use for the framebuffer.
+            color_attachments: The color attachments to use for the framebuffer."
+            depth_attachment: The depth attachment to use for the framebuffer."
+        """
         if color_attachments is None:
             color_attachments = []
         return context.framebuffer(
@@ -149,6 +178,19 @@ def from_file(
         angle: float = 0.0,
         filters=(gl.NEAREST, gl.NEAREST),
     ):
+        """ "
+        Create a BackgroundTexture from a file.
+        This is a convenience function to create a BackgroundTexture from a file.
+
+        The file is loaded using PIL and converted to a texture.
+
+        Args:
+            tex_src: The file to load.
+            offset: The offset of the texture in pixels.
+            scale: The scale of the texture.
+            angle: The angle of the texture in radians.
+            filters: The filters to use for the texture.
+        """
         _context = get_window().ctx
 
         with Image.open(resolve(tex_src)).convert("RGBA") as img:

arcade/future/light/lights.py

@@ -122,19 +122,23 @@ def __init__(self, width: int, height: int):
 
     @property
     def diffuse_texture(self):
+        """The diffuse texture"""
         return self.texture
 
     @property
     def light_texture(self):
+        """The light texture"""
         return self._light_buffer.color_attachments[0]
 
     def resize(self, width, height):
+        """Resize the light layer"""
         super().resize(width, height)
         self._light_buffer = self.ctx.framebuffer(
             color_attachments=self.ctx.texture((width, height), components=3)
         )
 
     def clear(self):
+        """Clear the light layer"""
         super().clear()
         self._light_buffer.clear()
 
@@ -145,6 +149,7 @@ def add(self, light: Light):
         self._rebuild = True
 
     def extend(self, lights: Sequence[Light]):
+        """Add a list of lights to the layer"""
         for light in lights:
             self.add(light)
 

arcade/gl/types.py

@@ -192,11 +192,17 @@ def __init__(
         location=0,
     ):
         self.name = name
+        """The name of the attribute in the program"""
         self.gl_type = gl_type
+        """The OpenGL type of the attribute"""
         self.components = components
+        """Number of components for this attribute (1, 2, 3 or 4)"""
         self.bytes_per_component = bytes_per_component
+        """How many bytes for a single component"""
         self.offset = offset
+        """Offset of the attribute in the buffer"""
         self.location = location
+        """Location of the attribute in the program"""
 
     @property
     def bytes_total(self) -> int:
@@ -408,13 +414,19 @@ def __init__(
         self, name: str, enum: GLenumLike, gl_type: PyGLenum, gl_size: int, components: int
     ):
         self.name = name
+        """The string representation of this type"""
         self.enum = enum
+        """The OpenEL enum of this type"""
         self.gl_type = gl_type
+        """The base OpenGL data type"""
         self.gl_size = gl_size
+        """The size of the base OpenGL data type"""
         self.components = components
+        """The number of components (1, 2, 3 or 4)"""
 
     @property
     def size(self) -> int:
+        """The total size of this type in bytes"""
         return self.gl_size * self.components
 
     def __repr__(self) -> str:

arcade/gl/uniform.py

@@ -1,5 +1,6 @@
 import struct
 from ctypes import POINTER, c_double, c_float, c_int, c_uint, cast
+from typing import Callable
 
 from pyglet import gl
 
@@ -173,8 +174,10 @@ def __init__(self, ctx, program_id, location, name, data_type, array_length):
         self._array_length = array_length
         # Number of components (including per array entry)
         self._components = 0
-        #: The getter function configured for this uniform
-        #: The setter function configured for this uniform
+        self.getter: Callable
+        """The getter function configured for this uniform"""
+        self.setter: Callable
+        """The setter function configured for this uniform"""
         self._setup_getters_and_setters()
 
     @property

arcade/isometric.py

@@ -5,6 +5,17 @@
 def isometric_grid_to_screen(
     tile_x: int, tile_y: int, width: int, height: int, tile_width: int, tile_height: int
 ) -> tuple[int, int]:
+    """
+    Convert isometric grid coordinates to screen coordinates.
+
+    Args:
+        tile_x: The x coordinate of the tile in the isometric grid.
+        tile_y: The y coordinate of the tile in the isometric grid.
+        width: The width of the screen.
+        height: The height of the screen.
+        tile_width: The width of a tile in pixels.
+        tile_height: The height of a tile in pixels.
+    """
     screen_x = tile_width * tile_x // 2 + height * tile_width // 2 - tile_y * tile_width // 2
     screen_y = (
         (height - tile_y - 1) * tile_height // 2
@@ -17,6 +28,17 @@ def isometric_grid_to_screen(
 def screen_to_isometric_grid(
     screen_x: int, screen_y: int, width: int, height: int, tile_width: int, tile_height: int
 ) -> tuple[int, int]:
+    """
+    Convert screen coordinates to isometric grid coordinates.
+
+    Args:
+        screen_x: The x coordinate on the screen.
+        screen_y: The y coordinate on the screen.
+        width: The width of the screen.
+        height: The height of the screen.
+        tile_width: The width of a tile in pixels.
+        tile_height: The height of a tile in pixels.
+    """
     x2 = (1 / tile_width * screen_x / 2 - 1 / tile_height * screen_y / 2 + width / 2) * 2 - (
         width / 2 + 0.5
     )
@@ -31,6 +53,17 @@ def screen_to_isometric_grid(
 def create_isometric_grid_lines(
     width: int, height: int, tile_width: int, tile_height: int, color: RGBA255, line_width: int
 ) -> ShapeElementList:
+    """
+    Create a ShapeElementList of isometric grid lines.
+
+    Args:
+        width: The width of the grid in tiles.
+        height: The height of the grid in tiles.
+        tile_width: The width of a tile in pixels.
+        tile_height: The height of a tile in pixels.
+        color: The color of the lines.
+        line_width: The width of the lines.
+    """
     # Grid lines 1
     shape_list: ShapeElementList = ShapeElementList()
 

arcade/pymunk_physics_engine.py

@@ -499,6 +499,15 @@ def set_position(self, sprite: Sprite, position: pymunk.Vec2d | tuple[float, flo
         physics_object.body.position = position
 
     def set_rotation(self, sprite: Sprite, rotation: float) -> None:
+        """
+        Set the rotation of the sprite
+
+        Args:
+            sprite:
+                A sprite known to the physics engine.
+            rotation:
+                The angle in degrees (clockwise).
+        """
         physics_object = self.get_physics_object(sprite)
         if physics_object.body is None:
             raise PymunkException(

doc/conf.py

@@ -18,7 +18,8 @@
 UTIL_DIR = REPO_LOCAL_ROOT / "util"
 
 log = logging.getLogger('conf.py')
-logging.basicConfig(level=logging.INFO)
+logging.basicConfig(level=logging.WARNING)
+# logging.basicConfig(level=logging.INFO)
 
 sys.path.insert(0, str(REPO_LOCAL_ROOT))
 sys.path.insert(0, str(ARCADE_MODULE))
@@ -513,12 +514,12 @@ def run(self) -> tuple[list[nodes.Node], list[nodes.system_message]]:
 
 
 def setup(app):
-    print("Diagnostic info since readthedocs doesn't use our make.py:")
+    log.info("Diagnostic info since readthedocs doesn't use our make.py:")
     for attr, comment in APP_CONFIG_DIRS:
         val = getattr(app, attr, None)
-        print(f"  {attr}: {val!r}")
+        log.info(f"{attr}: {val!r}")
         if comment:
-            print(f"    {comment}")
+            log.info(f"    {comment}")
 
     # Separate stylesheets loosely by category.
     # pending:  sphinx >= 8.1.4 to remove the sphinx_static_file_temp_fix.py