Fix broken references in docs: First pass (#2616)

* Enable nitpicky mode

* Sound.source was never exposed in docs

* Fix broken refs in sound manual

* Fix performance_tips

* Fix gui docs

* Fix event_loop

* arcade.gl: Remove optional markers in docstrings

* gl module fixes

* Remove optional annotations in napoleon docstrings

* Camera fixes

* Fix a loose reference to pyglet.math.Vec3 by prefixing the full path

* More doc fixes

* Missing docstrings in camera module

* More fixes

* Disable nitpicky

---------

Co-authored-by: pushfoo <[email protected]>

Author: einarf

CONTRIBUTING.md

@@ -103,7 +103,7 @@ The minium for docstrings is covering all parameters in an `Args:` block.
 Args:
     width: The width of something
     height: The height of something
-    title (optional): The title of something
+    title: The title of something
 ```
 
 * `Args:` should be used for all parameters
@@ -115,7 +115,6 @@ Args:
 * `Attributes:` we should try to avoid it and instead document the attributes in the code
 * Types are visible in the api docs. It's not mandatory to include types in docstring,
   however, simple types like `int`, `str`, `float`, `bool` can be included.
-* Using `optional` is a good way to indicate that a parameter is optional.
 * Properties and attribute docs don't need a type when this is already clear from
   type or return annotation.
 

arcade/application.py

@@ -86,51 +86,51 @@ class Window(pyglet.window.Window):
     .. _pyglet_pg_window_style: https://pyglet.readthedocs.io/en/latest/programming_guide/windowing.html#window-style
 
     Args:
-        width (optional):
+        width:
             Window width. Defaults to 1280.
-        height (optional):
+        height:
             Window height. Defaults to 720.
-        title (optional):
+        title:
             The title/caption of the window
-        fullscreen (optional):
+        fullscreen:
             Should this be full screen?
-        resizable (optional):
+        resizable:
             Can the user resize the window?
-        update_rate (optional):
+        update_rate:
             How frequently to run the on_update event.
-        draw_rate (optional):
+        draw_rate:
             How frequently to run the on_draw event. (this is the FPS limit)
-        fixed_rate (optional):
+        fixed_rate:
             How frequently should the fixed_updates run,
             fixed updates will always run at this rate.
-        fixed_frame_cap (optional):
+        fixed_frame_cap:
             The maximum number of fixed updates that can occur in one update loop.
             defaults to infinite. If large lag spikes cause your game to freeze,
             try setting this to a smaller number. This may cause your physics to
             lag behind temporarily.
-        antialiasing (optional):
+        antialiasing:
             Use multisampling framebuffer (antialiasing)
         samples: Number of samples used in antialiasing (default 4).
             Usually this is 2, 4, 8 or 16.
-        gl_version (optional): What OpenGL version to request.
+        gl_version: What OpenGL version to request.
             This is ``(3, 3)`` by default and can be overridden when using more
             advanced OpenGL features.
-        screen (optional): Pass a pyglet :py:class:`~pyglet.display.Screen` to
+        screen: Pass a pyglet :py:class:`~pyglet.display.Screen` to
             request the window be placed on it. See `pyglet's window size &
             position guide <pyglet_pg_window_size_position_>`_ to learn more.
-        style (optional): Request a non-default window style, such as borderless.
+        style: Request a non-default window style, such as borderless.
             Some styles only work in certain situations. See `pyglet's guide
             to window style <pyglet_pg_window_style_>`_ to learn more.
-        visible (optional):
+        visible:
             Should the window be visible immediately
-        vsync (optional):
+        vsync:
             Wait for vertical screen refresh before swapping buffer
             This can make animations and movement look smoother.
-        gc_mode (optional): Decides how OpenGL objects should be garbage collected
+        gc_mode: Decides how OpenGL objects should be garbage collected
             ("context_gc" (default) or "auto")
-        center_window (optional):
+        center_window:
             If true, will center the window.
-        enable_polling (optional):
+        enable_polling:
             Enabled input polling capability.
             This makes the :py:attr:`keyboard` and :py:attr:`mouse` attributes available for use.
 
@@ -356,17 +356,17 @@ def clear(  # type: ignore # not sure what to do here, BaseWindow.clear is stati
         set through :py:attr:`~arcade.Window.background_color`.
 
         Args:
-            color (optional):
+            color:
                 Override the current background color with one of the following:
 
                 1. A :py:class:`~arcade.types.Color` instance
                 2. A 3 or 4-length RGB/RGBA :py:class:`tuple` of byte values (0 to 255)
 
-            color_normalized (optional):
+            color_normalized:
                 override the current background color using normalized values (0.0 to 1.0).
                 For example, (1.0, 0.0, 0.0, 1.0) making the window contents red.
 
-            viewport (optional):
+            viewport:
                 The area of the window to clear. By default, the entire window is cleared.
                 The viewport format is ``(x, y, width, height)``.
         """
@@ -455,19 +455,19 @@ def set_fullscreen(
         to the size it was before entering fullscreen mode.
 
         Args:
-            fullscreen (optional):
+            fullscreen:
                 Should we enter or leave fullscreen mode?
-            screen (optional):
+            screen:
                 Which screen should we display on? See :func:`get_screens`
-            mode (optional):
+            mode:
                 The screen will be switched to the given mode.  The mode must
                 have been obtained by enumerating `Screen.get_modes`.  If
                 None, an appropriate mode will be selected from the given
                 `width` and `height`.
-            width (optional):
-                Override the width of the window. Will be rounded to :py:attr:`int`.
-            height (optional):
-                Override the height of the window. Will be rounded to :py:attr:`int`.
+            width:
+                Override the width of the window. Will be rounded to :py:class:`int`.
+            height:
+                Override the height of the window. Will be rounded to :py:class:`int`.
         """
         # fmt: off
         super().set_fullscreen(
@@ -1280,7 +1280,7 @@ class View:
     and a game over screen. Each of these could be a different view.
 
     Args:
-        window (optional):
+        window:
             The window this view is associated with. If None, the current
             window is used. (Normally you don't need to provide this).
     """
@@ -1304,15 +1304,15 @@ def clear(
         set through :py:attr:`arcade.View.background_color`.
 
         Args:
-            color(optional):
+            color:
                 override the current background color with one of the following:
 
                 1. A :py:class:`~arcade.types.Color` instance
                 2. A 3 or 4-length RGB/RGBA :py:class:`tuple` of byte values (0 to 255)
-            color_normalized (optional):
+            color_normalized:
                 Override the current background color using normalized values (0.0 to 1.0).
                 For example, (1.0, 0.0, 0.0, 1.0) making the window contents red.
-            viewport (optional):
+            viewport:
                 The viewport range to clear
         """
         if color is None and color_normalized is None:

arcade/camera/camera_2d.py

@@ -197,10 +197,10 @@ def from_camera_data(
 
         Args:
             camera_data:
-                A :py:class:`~arcade.camera.data.CameraData`
+                A :py:class:`~arcade.camera.CameraData`
                 describing the position, up, forward and zoom.
             projection_data:
-                A :py:class:`~arcade.camera.data.OrthographicProjectionData`
+                A :py:class:`~arcade.camera.OrthographicProjectionData`
                 which describes the left, right, top, bottom, far, near
                 planes and the viewport for an orthographic projection.
             render_target:
@@ -377,10 +377,10 @@ def match_target(
         Sets the viewport to the size of the Camera2D's render target.
 
         Args:
-            viewport: Flag whether to equalise the viewport to the area of the render target
-            projection: Flag whether to equalise the size of the projection to
-                match the render target
-            The projection center stays fixed, and the new projection matches only in size.
+            viewport: Flag whether to equalize the viewport to the area of the render target
+            projection: Flag whether to equalize the size of the projection to
+                match the render target.
+                The projection center stays fixed, and the new projection matches only in size.
             scissor: Flag whether to update the scissor value.
             position: Flag whether to also center the camera to the value.
                 Off by default
@@ -415,14 +415,14 @@ def update_values(
         aspect: float | None = None,
     ):
         """
-        Convienence method for updating the viewport, projection, position
+        Convenience method for updating the viewport, projection, position
         and a few others with the same value.
 
         Args:
             value: The rect that the values will be derived from.
-            viewport: Flag whether to equalise the viewport to the value.
-            projection: Flag whether to equalise the size of the projection to match the value.
-            The projection center stays fixed, and the new projection matches only in size.
+            viewport: Flag whether to equalize the viewport to the value.
+            projection: Flag whether to equalize the size of the projection to match the value.
+                The projection center stays fixed, and the new projection matches only in size.
             scissor: Flag whether to update the scissor value.
             position: Flag whether to also center the camera to the value.
                 Off by default
@@ -456,6 +456,7 @@ def update_values(
     def aabb(self) -> Rect:
         """
         Retrieve the axis-aligned bounds box of the camera's view area.
+
         If the camera isn't rotated , this will be precisely the view area,
         but it will cover a larger area when it is rotated. Useful for CPU culling
         """

arcade/camera/data_types.py

@@ -417,15 +417,14 @@ def use(self) -> None:
            :py:attr:`~arcade.Window.current_camera` to this object
         #. Calculate any required view and projection matrices
         #. Set any resulting values on the current
-           :py:class:`~arcade.context.ArcadeContext`, including the:
+           :py:class:`~arcade.ArcadeContext`, including the:
 
-           * :py:attr:`~arcade.context.ArcadeContext.viewport`
-           * :py:attr:`~arcade.context.ArcadeContext.view_matrix`
-           * :py:attr:`~arcade.context.ArcadeContext.projection_matrix`
+           * :py:attr:`~arcade.ArcadeContext.viewport`
+           * :py:attr:`~arcade.ArcadeContext.view_matrix`
+           * :py:attr:`~arcade.ArcadeContext.projection_matrix`
 
         This method should **never** handle cleanup. That is the
         responsibility of :py:attr:`.activate`.
-
         """
         ...
 

arcade/camera/perspective.py

@@ -108,15 +108,15 @@ def generate_projection_matrix(self) -> Mat4:
         """Generates a projection matrix.
 
         This is an alias of
-        :py:class:`arcade.camera.get_perspective_matrix`.
+        :py:meth:`generate_perspective_matrix`.
         """
         return generate_perspective_matrix(self._projection, self._view.zoom)
 
     def generate_view_matrix(self) -> Mat4:
         """Generates a view matrix.
 
         This is an alias of=
-        :py:class:`arcade.camera.get_view_matrix`.
+        :py:meth:`generate_view_matrix`.
         """
         return generate_view_matrix(self._view)
 
@@ -171,7 +171,7 @@ def project(self, world_coordinate: Point) -> Vec2:
         """Convert world coordinates to pixel screen coordinates.
 
         If a 2D :py:class:`~pyglet.math.Vec2` is provided instead of a 3D
-        :py:class:`Vec3`, then one will be calculated to the best of the
+        :py:class:`~pyglet.math.Vec3`, then one will be calculated to the best of the
         method's ability.
 
         Args:

arcade/camera/projection_functions.py

@@ -125,6 +125,15 @@ def project_orthographic(
     view_matrix: Mat4,
     projection_matrix: Mat4,
 ) -> Vec2:
+    """
+    Project a world coordinate to a screen coordinate using an orthographic projection.
+
+    Args:
+        world_coordinate: The world coordinate to project.
+        viewport: The viewport of the camera.
+        view_matrix: The view matrix of the camera.
+        projection_matrix: The projection matrix of the camera.
+    """
     x, y, *_z = world_coordinate
     z = 0.0 if not _z else _z[0]
 
@@ -144,6 +153,15 @@ def unproject_orthographic(
     view_matrix: Mat4,
     projection_matrix: Mat4,
 ) -> Vec3:
+    """
+    Unproject a screen coordinate to a world coordinate using an orthographic projection.
+
+    Args:
+        screen_coordinate: The screen coordinate to unproject.
+        viewport: The viewport of the camera.
+        view_matrix: The view matrix of the camera.
+        projection_matrix: The projection matrix of the camera.
+    """
     x, y, *_z = screen_coordinate
     z = 0.0 if not _z else _z[0]
 
@@ -165,6 +183,15 @@ def project_perspective(
     view_matrix: Mat4,
     projection_matrix: Mat4,
 ) -> Vec2:
+    """
+    Project a world coordinate to a screen coordinate using a perspective projection.
+
+    Args:
+        world_coordinate: The world coordinate to project.
+        viewport: The viewport of the camera.
+        view_matrix: The view matrix of the camera.
+        projection_matrix: The projection matrix of the camera.
+    """
     x, y, *_z = world_coordinate
     z = 1.0 if not _z else _z[0]
 
@@ -188,6 +215,15 @@ def unproject_perspective(
     view_matrix: Mat4,
     projection_matrix: Mat4,
 ) -> Vec3:
+    """
+    Unproject a screen coordinate to a world coordinate using a perspective projection.
+
+    Args:
+        screen_coordinate: The screen coordinate to unproject.
+        viewport: The viewport of the camera.
+        view_matrix: The view matrix of the camera.
+        projection_matrix: The projection matrix of
+    """
     x, y, *_z = screen_coordinate
     z = 1.0 if not _z else _z[0]
 

arcade/context.py

@@ -358,23 +358,23 @@ def load_program(
         Args:
             vertex_shader:
                 Path to the vertex shader.
-            fragment_shader (optional):
-                Path to the fragment shader (optional).
-            geometry_shader (optional):
-                Path to the geometry shader (optional).
-            tess_control_shader (optional):
+            fragment_shader:
+                Path to the fragment shader.
+            geometry_shader:
+                Path to the geometry shader.
+            tess_control_shader:
                 Tessellation Control Shader.
-            tess_evaluation_shader (optional):
+            tess_evaluation_shader:
                 Tessellation Evaluation Shader.
-            common (optional):
+            common:
                 Common files to be included in all shaders.
-            defines (optional):
+            defines:
                 Substitute `#define` values in the source.
-            varyings (optional):
+            varyings:
                 The name of the out attributes in a transform shader.
                 This is normally not necessary since we auto detect them,
                 but some more complex out structures we can't detect.
-            varyings_capture_mode (optional):
+            varyings_capture_mode:
                 The capture mode for transforms.
 
                 Based on these settings, the `transform()` method will accept a single
@@ -435,7 +435,7 @@ def load_compute_shader(
         Args:
             path:
                 Path to texture
-            common (optional):
+            common:
                 Common sources injected into compute shader
         """
         from arcade.resources import resolve
@@ -492,13 +492,13 @@ def load_texture(
                 The min and mag filter. Default is ``None``.
             build_mipmaps:
                 Build mipmaps for the texture. Default is ``False``.
-            internal_format (optional):
+            internal_format:
                 The internal format of the texture. This can be used to override
                 the default internal format when using sRGBA or compressed textures.
-            immutable (optional):
+            immutable:
                 Make the storage (not the contents) immutable. This can sometimes be
                 required when using textures with compute shaders.
-            compressed (optional):
+            compressed:
                 If the internal format is a compressed format meaning your
                 texture will be compressed by the GPU.
         """