Documentation improvements (#2634)

* refs in resources

* platform_tutorial

* pymunk_platformer

* views

* card_game

* Notice in shader tutorials

* menu tutorial

* sections

* spritelists

* opengl_notes

* resource_handlers

* texture_atlas

Author: einarf

arcade/resources/__init__.py

@@ -36,7 +36,7 @@ def resolve_resource_path(path: str | Path) -> Path:
     If the path is a string it tries to resolve it as a resource handle
     or convert it to a Path object.
 
-    If the path is a Path object it will ``Path.resolve()`` it
+    If the path is a Path object it will :py:meth:`~pathlib.Path.resolve` it
     unless it's not absolute and return it.
 
     Example::
@@ -57,7 +57,7 @@ def resolve(path: str | Path) -> Path:
     If the path is a string it tries to resolve it as a resource handle
     or convert it to a Path object.
 
-    If the path is a Path object it will ``Path.resolve()`` it
+    If the path is a Path object it will :py:meth:`~pathlib.Path.resolve` it
     unless it's not absolute and return it.
 
     Example::

doc/programming_guide/opengl_notes.rst

@@ -91,7 +91,7 @@ SpriteList & Threads
 SpriteLists can be created in threads if they are
 created with the ``lazy=True`` parameters.
 This ensures OpenGL resources are not created until the
-first ``draw()`` call or ``initialize()`` is called.
+first :py:meth:`~arcade.SpriteList.draw()` call or :py:meth:`~arcade.SpriteList.initialize` is called.
 
 .. _prog-guide-gl-buffer-protocol-typing:
 

doc/programming_guide/resource_handlers.rst

@@ -221,7 +221,7 @@ Import the Path Class Before Arcade
 """""""""""""""""""""""""""""""""""
 
 To use :py:mod:`pathlib`, you usually only need to import
-py:class:`~pathlib.Path` from it.
+:py:class:`~pathlib.Path` from it.
 
 Since Python developers usually import built-ins before add-on
 libraries like Arcade, we'll do the same here:

doc/programming_guide/sections.rst

@@ -228,7 +228,7 @@ Properties of a :class:`~arcade.Section`:
 Other handy :class:`~arcade.Section` properties:
 
 - block_updates: if True this section will not have the ``on_update`` method called.
-- camera: this is meant to hold a ``arcade.Camera`` but it is None by default. The SectionManager will trigger the use of the camera when is needed automatically.
+- camera: this is meant to hold a :py:class:`~arcade.Camera2D` but it is None by default. The SectionManager will trigger the use of the camera when is needed automatically.
 
 Handy :class:`~arcade.Section`: methods:
 

doc/programming_guide/sprites/spritelists.rst

@@ -12,7 +12,7 @@ Each sprite describes where a game object is & how to draw it. This includes:
 * Where to find the image data
 * How big the image should be
 
-The rest of this page will explain using the ``SpriteList`` class to draw
+The rest of this page will explain using the :py:class:`~arcade.SpriteList` class to draw
 sprites to the screen.
 
 

doc/programming_guide/texture_atlas.rst

@@ -55,7 +55,7 @@ Most users will not be aware that Arcade is using a texture
 atlas under the hood. More advanced users can take advantage
 of these if they run into limitations.
 
-Arcade has a global default texture atlas stored in ``window.ctx.default_atlas``.
+Arcade has a global default texture atlas stored in :py:attr:`arcade.Window.ctx.default_atlas`.
 This is an instance of :py:class:`arcade.ArcadeContext` where the low
 level rendering API is accessed (OpenGL).
 

doc/tutorials/card_game/index.rst

@@ -51,7 +51,7 @@ Card Class
 ~~~~~~~~~~
 
 Next up, we'll create a card class. The card class is a subclass of
-``arcade.Sprite``. It will have attributes for the suit and value of the
+:py:class:`~arcade.Sprite`. It will have attributes for the suit and value of the
 card, and auto-load the image for the card based on that.
 
 We'll use the entire image as the hit box, so we don't need to go through the

doc/tutorials/menu/index.rst

@@ -46,14 +46,14 @@ Modify the MainView
 ~~~~~~~~~~~~~~~~~~~~
 
 We are going to add a button to change the view. For drawing a button we would
-need a ``UIManager``.
+need an :py:class:`~arcade.gui.UIManager`.
 
 .. literalinclude:: menu_02.py
     :caption: Initialising the Manager
     :lines: 19-22
     :emphasize-lines: 3
 
-After initialising the manager we need to enable it when the view is shown and
+After initializing the manager we need to enable it when the view is shown and
 disable it when the view is hidden.
 
 .. literalinclude:: menu_02.py
@@ -74,12 +74,12 @@ We also need to draw the children of the menu in ``on_draw``.
     :emphasize-lines: 7
 
 Now we have successfully setup the manager, we can now add a button to the view.
-We are using ``UIAnchorLayout`` to position the button. We also setup a function
+We are using :py:class:`~arcade.gui.UIAnchorLayout` to position the button. We also setup a function
 which is called when the button is clicked.
 
   .. literalinclude:: menu_02.py
     :pyobject: MainView.__init__
-    :caption: Initialising the Button
+    :caption: Initializing the Button
     :emphasize-lines: 8-12
 
 Initialise the Menu View
@@ -123,7 +123,7 @@ First we setup buttons for resume, starting a new game, volume, options and exit
 Displaying the Buttons in a Grid
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-After setting up the buttons we add them to ``UIGridLayout``, so that they can
+After setting up the buttons we add them to :py:class:`~arcade.gui.UIGridLayout`, so that they can
 displayed in a grid like manner.
 
 .. literalinclude:: menu_03.py
@@ -167,7 +167,7 @@ Adding ``on_click`` Callback for Volume and Options
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Now we need to implement an actual menu for volume and options, for that we have
-to make a class that acts like a window. Using ``UIMouseFilterMixin`` we catch
+to make a class that acts like a window. Using :py:class:`~arcade.gui.UIMouseFilterMixin` we catch
 all the events happening for the parent and respond nothing to them. Thus
 making it act like a window/view.
 
@@ -221,7 +221,7 @@ Now you might be getting a little idea why we have edited the parameters but
 Adding a Title label
 --------------------
 
-We will be adding a ``UILabel`` that explains the menu. ``UISpace`` is a widget
+We will be adding a :py:class:`~arcade.gui.UILabel` that explains the menu. :py:class:`~arcade.gui.UISpace` is a widget
 that can be used to add space around some widget, you can set its color to the
 background color so it appears invisible.
 
@@ -236,10 +236,10 @@ Adding it to the widget layout.
     :lines: 238-239
 
 
-Adding a Input Field
+Adding an Input Field
 ~~~~~~~~~~~~~~~~~~~~~
 
-We will use ``UIInputText`` to add an input field. The ``with_border()``
+We will use :py:class:`~arcade.gui.UIInputText` to add an input field. The :py:meth:`~arcade.gui.UIWidget.with_border`
 function creates a border around the widget with color(default argument is
 black) black and thickness(default argument is 2px) 2px. Add this just below
 the title label.
@@ -263,7 +263,7 @@ in the last also for those of you who are skipping through this section :P.
 Adding a Toggle Button
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Don't go on the section title much, in Arcade the ``UITextureToggle`` is not
+Don't go on the section title much, in Arcade the :py:class:`~arcade.gui.UITextureToggle` is not
 really a button it switches between two textures when clicked. Yes, it
 functions like a button but by "is not really a button" we meant that it
 doesn't inherits the button class. We also pair it up horizontally with the
@@ -283,7 +283,7 @@ field.
 Adding a Dropdown
 ~~~~~~~~~~~~~~~~~
 
-We add a dropdown by using ``UIDropdown``.
+We add a dropdown by using :py:class:`~arcade.gui.UIDropdown`.
 
 .. literalinclude:: menu_05.py
     :caption: Adding dropdown
@@ -298,9 +298,9 @@ Adding it to the widget layout.
 Adding a Slider
 ~~~~~~~~~~~~~~~
 
-The final widget. In Arcade you can use ``UISlider`` to implement a slider. 
+The final widget. In Arcade you can use :py:class:`~arcade.gui.UISlider` to implement a slider. 
 Theres a functionality to style the slider, this is also present for 
-``UIFlatButton`` and ``UITextureButton``.
+:py:class:`~arcade.gui.UIFlatButton` and :py:class:`~arcade.gui.UITextureButton`.
 
 .. literalinclude:: menu_05.py
     :caption: Adding slider

doc/tutorials/platform_tutorial/step_04.rst

@@ -46,7 +46,7 @@ functions, based on the key that was pressed or released, we will move our chara
         elif key == arcade.key.RIGHT or key == arcade.key.D:
             self.player_sprite.change_x = 0
 
-In these boxes, we are modifying the ``change_x`` and ``change_y`` attributes on our
+In these boxes, we are modifying the :py:attr:`~arcade.Sprite.change_x` and :py:attr:`~arcade.Sprite.change_y` attributes on our
 player Sprite. Changing these values will not actually perform the move on the Sprite.
 In order to apply this change, we need to create a physics engine with our Sprite,
 and update the physics engine every frame. The physics engine will then be responsible

doc/tutorials/pymunk_platformer/index.rst

@@ -88,7 +88,7 @@ lines of code like this:
     self.player_list: Optional[arcade.SpriteList] = None
 
 This means the ``player_list`` attribute is going to be an instance of
-``SpriteList`` or ``None``. If you don't want to mess with typing, then
+:py:class:`~arcade.SpriteList` or ``None``. If you don't want to mess with typing, then
 this code also works just as well:
 
 .. code-block::
@@ -121,7 +121,7 @@ If you aren't sure how to use the Tiled Map Editor, see :ref:`platformer_part_ei
 
 Now, in the ``setup`` function, we are going add code to:
 
-* Create instances of ``SpriteList`` for each group of sprites we are doing
+* Create instances of :py:class:`~arcade.SpriteList` for each group of sprites we are doing
   to work with.
 * Create the player sprite.
 * Read in the tiled map.
@@ -298,7 +298,7 @@ Then we will adjust the left/right force depending on if we are grounded or not:
 Add Player Animation
 --------------------
 
-To create a player animation, we make a custom child class of ``Sprite``.
+To create a player animation, we make a custom child class of :py:class:`~arcade.Sprite`.
 We load each frame of animation that we need, including a mirror image of it.
 
 We will flip the player to face left or right. If the player is in the air, we'll
@@ -318,7 +318,7 @@ animation, so that the feet appear in-sync with the ground.
     :linenos:
     :lines: 58-66
 
-Next, we create a ``Player`` class that is a child to ``arcade.Sprite``. This
+Next, we create a ``Player`` class that is a child to :py:class:`~arcade.Sprite`. This
 class will update the player animation.
 
 The ``__init__`` method loads all of the textures. Here we use Kenney.nl's
@@ -327,8 +327,8 @@ It has six different characters you can choose from with the same layout, so
 it makes changing as simple as changing which line is enabled. There are
 eight textures for walking, and textures for idle, jumping, and falling.
 
-As the character can face left or right, we use ``arcade.load_texture_pair``
-which will load both a regular image, and one that's mirrored.
+As the character can face left or right, we prepare a standard and mirrored
+version of each texture by using :py:meth:`~arcade.Texture.flip_left_right`.
 
 For the multi-frame walking animation, we use an "odometer." We need to move
 a certain number of pixels before changing the animation. If this value is too
@@ -344,7 +344,7 @@ called. This can be used to update the animation.
     :linenos:
     :pyobject: PlayerSprite
 
-Important! At this point, we are still creating an instance of ``arcade.Sprite``
+Important! At this point, we are still creating an instance of :py:class:`~arcade.Sprite`
 and **not** ``PlayerSprite``. We need to go back to the ``setup`` method and
 replace the line that creates the ``player`` instance with:
 
@@ -434,7 +434,7 @@ If our y value is too low, we'll remove the bullet.
     :pyobject: BulletSprite
 
 And, of course, once we create the bullet we have to update our code to use
-it instead of the plain ``arcade.Sprite`` class.
+it instead of the plain :py:class:`~arcade.Sprite` class.
 
 .. literalinclude:: pymunk_demo_platformer_10.py
     :caption: Destroy Bullets - Bullet Sprite