From a0e32274c76e9c99634040ee0818cd1f9688b854 Mon Sep 17 00:00:00 2001 From: Paul V Craven Date: Fri, 9 Oct 2026 14:47:40 -0500 Subject: [PATCH] Fix broken links in the docs - 19 named links like `Discord `_ were missing the trailing underscore that makes the name a reference, so docutils linked to pages called "Arcade Discord" etc. The Swedish and German textbook links also had no targets. - Two "How to Get Help" links pointed at section labels as URLs. - A malformed CONTRIBUTING.md link in PymunkPhysicsEngine's docstring. - The resources page used absolute /_static/ paths, which only worked on Read the Docs, where the site URL was prefixed. They're relative now. - Six dead external links: the CPython GC docs moved, a quaternion article is gone (archived copy), the Nuitka tutorial pointed at 17_views.py (now 20_views.py), pyglet's master docs, a renamed Kenney asset page, and a community game whose repo no longer exists. Co-Authored-By: Claude Opus 5.5 --- arcade/application.py | 2 +- arcade/math.py | 2 +- arcade/pymunk_physics_engine.py | 2 +- doc/_includes/resources_Video.rst | 2 +- doc/about/for_academia.rst | 11 ++++++---- doc/about/permissive_licensing.rst | 2 +- doc/community/games/sample_games.rst | 4 +--- doc/community/how_to_get_help.rst | 4 ++-- doc/contributing/index.rst | 6 +++--- doc/programming_guide/gles_raspi_and_sbc.rst | 12 +++++------ doc/programming_guide/sound.rst | 2 +- doc/tutorials/compiling_with_nuitka/index.rst | 20 +++++++++---------- doc/tutorials/pymunk_platformer/index.rst | 2 +- util/create_resources_listing.py | 12 ++++++++--- 14 files changed, 45 insertions(+), 38 deletions(-) diff --git a/arcade/application.py b/arcade/application.py index fef04a98b9..e81146e67f 100644 --- a/arcade/application.py +++ b/arcade/application.py @@ -875,7 +875,7 @@ def set_mouse_cursor_visible(self, visible: bool = True) -> None: arrows by using features :class:``~arcade.Window`` inherits from the underlying pyglet window class. See the `pyglet overview on cursors - `_ + `_ for more information. Args: diff --git a/arcade/math.py b/arcade/math.py index c31760fa22..f0109f04ef 100644 --- a/arcade/math.py +++ b/arcade/math.py @@ -471,7 +471,7 @@ def quaternion_rotation(axis: Point3, vector: Point3, angle: float) -> tuple[flo This method of vector rotation is immune to rotation-lock, however it takes a little more effort to find the axis of rotation rather than 3 angles of rotation. - Ref: https://danceswithcode.net/engineeringnotes/quaternions/quaternions.html. + Ref: https://web.archive.org/web/20240207004539/https://danceswithcode.net/engineeringnotes/quaternions/quaternions.html Args: axis (tuple[float, float, float]): The unit length vector that will be rotated around diff --git a/arcade/pymunk_physics_engine.py b/arcade/pymunk_physics_engine.py index ab68c49d29..2d7be7240e 100644 --- a/arcade/pymunk_physics_engine.py +++ b/arcade/pymunk_physics_engine.py @@ -45,7 +45,7 @@ class PymunkPhysicsEngine: .. note:: Arcade would welcome assistance with improving it. If you are interested, please see Arcade's - `CONTRIBUTING.md `_ + `CONTRIBUTING.md `_ Args: gravity: diff --git a/doc/_includes/resources_Video.rst b/doc/_includes/resources_Video.rst index 66029bf6a2..eeaa296203 100644 --- a/doc/_includes/resources_Video.rst +++ b/doc/_includes/resources_Video.rst @@ -15,5 +15,5 @@ examples below may require installing both :ref:`guide-supportedmedia-ffmpeg` an The links above use the unstable development branch of Arcade to gain access to the latest pyglet and Arcade features. If you have questions or want to help develop these examples further, we'd love to hear -from you. The Arcade `Discord server `_ and `GitHub repository `_ always welcome +from you. The Arcade `Discord server `_ and `GitHub repository `_ always welcome new community members. diff --git a/doc/about/for_academia.rst b/doc/about/for_academia.rst index e80a3e85a4..e367d32c6d 100644 --- a/doc/about/for_academia.rst +++ b/doc/about/for_academia.rst @@ -32,7 +32,7 @@ To learn more about using this template, please consult the following: Version Considerations ---------------------- -Most users will be best served by `Arcade's latest release from PyPI `_ +Most users will be best served by `Arcade's latest release from PyPI `_ For new games, the features and improved efficiency of Arcade 3 make it the best choice. Upgrading existing games is also worthwhile. @@ -47,10 +47,10 @@ companion :ref:`academia_arcade_book` covered in depth below. Arcade Textbook ^^^^^^^^^^^^^^^ -The creator of Arcade wrote an `Arcade Textbook `_ which covers Python basics +The creator of Arcade wrote an `Arcade Textbook `_ which covers Python basics n greater depth than the main Arcade documentation. -It may be a while before the `Arcade Textbook `_ is updated for Arcade 3.0. This +It may be a while before the `Arcade Textbook `_ is updated for Arcade 3.0. This is a large undertaking due to the number and scale of changes since Arcade 2.6. @@ -71,7 +71,10 @@ in a traditional chapter and curriculum structure: #. Embedded videos covering concepts and past student projects #. Lab exercises to help apply chapter material through practice -#. Translations in `Swedish / Svenska `_ and `German / Deutsche `_ +#. Translations in `Swedish / Svenska `_ and `German / Deutsche `_ + +.. _book_sv: https://learn.arcade.academy/sv/latest/ +.. _book_de: https://learn.arcade.academy/de/latest/ It also offers gentle, beginner-friendly introductions to topics which can intimidate even the graduates of college-level computer science programs: diff --git a/doc/about/permissive_licensing.rst b/doc/about/permissive_licensing.rst index 0c402abc19..d561d0b7b0 100644 --- a/doc/about/permissive_licensing.rst +++ b/doc/about/permissive_licensing.rst @@ -19,7 +19,7 @@ Yes, You Can Make Commercial Games! There is already a commercially available game made with Arcade. -`Spelly Cat`_ is a puzzle game available via Valve Software's `Steam marketplace `_. +`Spelly Cat`_ is a puzzle game available via Valve Software's `Steam marketplace `_. It is currently available for Windows and Linux. .. important:: Arcade is currently a desktop-focused framework. diff --git a/doc/community/games/sample_games.rst b/doc/community/games/sample_games.rst index 1a313bf320..e3f3c1cf69 100644 --- a/doc/community/games/sample_games.rst +++ b/doc/community/games/sample_games.rst @@ -261,9 +261,7 @@ A space-themed typing game by thecodeah. .. image:: /images/community/games/space_typer.png :width: 75% -`GitHub repo for Space Typer`_ - -.. _GitHub repo for Space Typer: https://github.com/thecodeah/space-typer +The source code is no longer online. FlapPy Bird diff --git a/doc/community/how_to_get_help.rst b/doc/community/how_to_get_help.rst index 94a458e87f..1917695b88 100644 --- a/doc/community/how_to_get_help.rst +++ b/doc/community/how_to_get_help.rst @@ -216,7 +216,7 @@ half of each line may change to reflect your Arcade version, hardware, and operating system. You can copy and paste the output into Discord or GitHub using the -`markdown formatting for terminal output `_ +:ref:`markdown formatting for terminal output ` described earlier. Output like the example below means that something is wrong: @@ -225,7 +225,7 @@ Output like the example below means that something is wrong: bash: arcade: command not found -You should still `include the output `_ +You should still :ref:`include the output ` as part of a request for help. If you want to try fixing the problem yourself before getting help, diff --git a/doc/contributing/index.rst b/doc/contributing/index.rst index 2615566866..26b66b8847 100644 --- a/doc/contributing/index.rst +++ b/doc/contributing/index.rst @@ -28,7 +28,7 @@ documentation. It doesn't matter whether you've started :ref:`the platformer tutorial ` or just happen to be looking around. Let us know if anything looks off. -The best ways to report it are via `Discord `_ +The best ways to report it are via `Discord `_ or the `Arcade GitHub`_ repository, but we also have other :ref:`community-locations`. @@ -69,7 +69,7 @@ Report Bugs If you see something weird, let the devs know! -Whether it's via `GitHub `_ or the `Arcade Discord`_, +Whether it's via `GitHub `_ or the `Arcade Discord`_, even a simple screenshot or video capture can help us make Arcade better. This includes: @@ -101,5 +101,5 @@ the source of the problem. * If not, post a new one Don't worry too much about posting duplicates. We can always cross-reference -issues if it's a duplicate. If you're unsure, you can always ask on `Discord `_. +issues if it's a duplicate. If you're unsure, you can always ask on `Discord `_. diff --git a/doc/programming_guide/gles_raspi_and_sbc.rst b/doc/programming_guide/gles_raspi_and_sbc.rst index 5c8daf2cd0..1ab0962d7a 100644 --- a/doc/programming_guide/gles_raspi_and_sbc.rst +++ b/doc/programming_guide/gles_raspi_and_sbc.rst @@ -10,7 +10,7 @@ you may want to skip to :ref:`requirements_gles` below. OpenGL ES --------- -`OpenGL ES `_ ("embeddedable subset") is a special +`OpenGL ES `_ ("embeddedable subset") is a special variant of OpenGL tailored for mobile and embedded devices. Like the standard OpenGL API, it has both feature versions @@ -27,10 +27,10 @@ Supported Raspberry Pi Configurations As of October 2024, the Arcade and `pyglet`_ teams verified the following to work: -* `Raspberry Pi 4 `_ running `Raspberry Pi OS`_ -* `Raspberry Pi 5 `_ running `Raspberry Pi OS`_ +* `Raspberry Pi 4 `_ running `Raspberry Pi OS`_ +* `Raspberry Pi 5 `_ running `Raspberry Pi OS`_ -Although the `Raspberry Pi 400 `_ has never been tested, it +Although the `Raspberry Pi 400 `_ has never been tested, it *may* work. It uses Raspberry Pi 4 hardware inside a keyboard form factor. Operating Systems @@ -86,7 +86,7 @@ The table below lists these newer incompatible Raspberry Pi devices. * - Device - Type - * - `Pi Pico`_ (and W version) / `RP2040 `_ + * - `Pi Pico`_ (and W version) / `RP2040 `_ - Microcontroller * - `Pi Pico 2`_ (and W version) / `RP2350`_ @@ -129,7 +129,7 @@ Both Arcade and `pyglet`_ can run via OpenGL ES on devices with either: * OpenGL ES 3.2 or higher * OpenGL ES 3.1 with certain extensions -To learn more, please see the `pyglet manual page on OpenGL ES `_. +To learn more, please see the `pyglet manual page on OpenGL ES `_. .. pending: post-3.0 cleanup # Faster and more reliable than getting the external ref syntax to work .. _pyglet-opengles: https://pyglet.readthedocs.io/en/development/programming_guide/opengles.html diff --git a/doc/programming_guide/sound.rst b/doc/programming_guide/sound.rst index 32bd442ee0..4afbab42ec 100644 --- a/doc/programming_guide/sound.rst +++ b/doc/programming_guide/sound.rst @@ -351,7 +351,7 @@ There is no stop method. Instead, call .. rubric:: Stopping Permanently -.. _garbage collection: https://devguide.python.org/internals/garbage-collector/ +.. _garbage collection: https://github.com/python/cpython/blob/main/InternalDocs/garbage_collector.md After you've paused a player, you can stop playback permanently as follows: diff --git a/doc/tutorials/compiling_with_nuitka/index.rst b/doc/tutorials/compiling_with_nuitka/index.rst index 4dd2bb526a..6f00e3eec9 100644 --- a/doc/tutorials/compiling_with_nuitka/index.rst +++ b/doc/tutorials/compiling_with_nuitka/index.rst @@ -51,13 +51,13 @@ For this tutorial, we will use the code from :ref:`platformer_tutorial`. pip install nuitka -We will be using the code from `this file `_. +We will be using the code from `this file `_. Converting that code to a standalone executable is as easy as: .. code-block:: bash - python -m nuitka 17_views.py --standalone --enable-plugin=numpy + python -m nuitka 20_views.py --standalone --enable-plugin=numpy .. note:: @@ -67,9 +67,9 @@ Converting that code to a standalone executable is as easy as: Now sit back and relax. Might as well go and grab a cup of coffee since compilation takes time, sometimes maybe up to 2 hours, depending on your machine's specs. -After the process is finished, two new folders named ``17_views.py.dist`` and -``17_views.py.build`` will popup. You can safely ignore the build folder for now. -Just go to the dis folder and run ``17_views.exe`` file , present in there. If there are no +After the process is finished, two new folders named ``20_views.py.dist`` and +``20_views.py.build`` will popup. You can safely ignore the build folder for now. +Just go to the dis folder and run ``20_views.exe`` file , present in there. If there are no errors, then the application should work perfectly. Congratulations! You have successfully compiled your Python code to a standalone executable! @@ -87,7 +87,7 @@ etc... In order to bundle them with the application, just use the ``include-data .. code-block:: bash - python -m nuitka 17_views.py --standalone --enable-plugin=numpy --include-data-file=C:/Users/Hunter/Desktop/my_game/my_image.png=. + python -m nuitka 20_views.py --standalone --enable-plugin=numpy --include-data-file=C:/Users/Hunter/Desktop/my_game/my_image.png=. This will copy the file named ``my_image.png`` at the specified location to the root of the executable. @@ -95,7 +95,7 @@ To bundle a whole folder: .. code-block:: bash - python -m nuitka 17_views.py --standalone --enable-plugin=numpy --include-data-dir=C:/Users/Hunter/Desktop/my_game/assets=. + python -m nuitka 20_views.py --standalone --enable-plugin=numpy --include-data-dir=C:/Users/Hunter/Desktop/my_game/assets=. This will copy the whole folder named ``assets`` at the specified location to the root of the executable. @@ -113,7 +113,7 @@ this is also possible: .. code-block:: bash - python -m nuitka 17_views.py --standalone --windows-force-stderr-spec=%PROGRAM%logs.txt --windows-force-stdout-spec=%PROGRAM%output.txt + python -m nuitka 20_views.py --standalone --windows-force-stderr-spec=%PROGRAM%logs.txt --windows-force-stdout-spec=%PROGRAM%output.txt This will automatically create two files, viz ``logs.txt`` and ``output.txt`` in the executable directory which will contain the stderr and stdout output respectively! @@ -128,13 +128,13 @@ The first flag takes a ``.png`` or a ``.ico`` file and sets it as the app icon: .. code-block:: bash - python -m nuitka 17_views.py --standalone --windows-icon-from-ico=icon.png + python -m nuitka 20_views.py --standalone --windows-icon-from-ico=icon.png This will set the app icon to icon.png .. code-block:: bash - python -m nuitka 17_views.py --standalone --windows-icon-from-exe=C:\Users\Hunter\AppData\Local\Programs\Python\Python310/python.exe + python -m nuitka 20_views.py --standalone --windows-icon-from-exe=C:\Users\Hunter\AppData\Local\Programs\Python\Python310/python.exe This will set the app icon to Python's icon 😉 diff --git a/doc/tutorials/pymunk_platformer/index.rst b/doc/tutorials/pymunk_platformer/index.rst index e338c2df71..6dc72bbc4c 100644 --- a/doc/tutorials/pymunk_platformer/index.rst +++ b/doc/tutorials/pymunk_platformer/index.rst @@ -322,7 +322,7 @@ Next, we create a ``Player`` class that is a child to :py:class:`~arcade.Sprite` class will update the player animation. The ``__init__`` method loads all of the textures. Here we use Kenney.nl's -`Toon Characters 1 `_ pack. +`Toon Characters 1 `_ pack. 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. diff --git a/util/create_resources_listing.py b/util/create_resources_listing.py index 8b08654738..3ce9c0c431 100644 --- a/util/create_resources_listing.py +++ b/util/create_resources_listing.py @@ -63,9 +63,15 @@ def announce_templating(var_name): announce_templating("FMT_URL_REF_EMBED") -def src_kludge(strpath): # pending: post-3.0 cleanup: # evil evil evil evil - """We inject what RTD says the canonical domain is up top + the version""" - return f"{RTD_EVIL}{strpath}" +def src_kludge(strpath): + """Make a /_static/ path relative to the resources page. + + It's at api_docs/resources.html, so relative paths work both on + Read the Docs and in local builds. + """ + if not strpath.startswith("/"): + return strpath # Already a full URL + return "../" + strpath.lstrip("/") MODULE_DIR = Path(__file__).parent.resolve() ARCADE_ROOT = MODULE_DIR.parent