Skip to content

Fix broken cross-references in the docs - #2969

Merged
pvcraven merged 1 commit into
developmentfrom
fix-doc-references
Oct 9, 2026
Merged

pvcraven merged 1 commit into
developmentfrom
fix-doc-references

Conversation

@pvcraven

@pvcraven pvcraven commented Oct 9, 2026

Copy link
Copy Markdown
Member

Part 1 of #2297. The next PR turns on nitpicky = True.

A nitpicky build (sphinx-build -n) reported 409 unresolved references. This PR fixes the ones that were really broken: links readers can click today that go nowhere, about 160 warnings. That group goes from 161 to 10. The other 265 are type variables, other libraries' internals and undocumented type aliases, which the second PR handles with config.

What was wrong

  • Typos:
    • interesection
    • allow_multi_jumps (should be allow_multi_jump)
    • scale_multiply_uniform (should be multiply_scale)
    • add_spritelist (should be add_sprite_list)
    • unique_textures` (stray backtick)
    • :py:class:`TypeError.` (period inside the role)
  • Names that no longer exist:
    • arcade.Camera (now Camera2D)
    • set_velocity_horizontal / set_velocity_vertical (now set_horizontal_velocity; there is no vertical one)
    • arcade.utils.ByteRangeError (now in arcade.exceptions)
    • old arcade.future.input paths
    • UIMouseEvents, arcade.gui.UIElement, Limits.POINT_SIZE_RANGE
    • Box.kwargs and Box.from_kwargs, which don't exist. The Box docstring listed .from_kwargs, which linked to Rect.from_kwargs.
  • Paths the docs don't publish:
    • arcade.sprite.sprite.Sprite.* → arcade.Sprite.*
    • arcade.gl.Context.* → arcade.gl.context.Context.*
    • arcade.gl.Buffer → arcade.gl.buffer.Buffer
    • arcade.tilemap.TileMap → arcade.tilemap.tilemap.TileMap
    • SpriteList.geometry → SpriteListData.geometry
    • short names like View.on_show_view, UIScrollBar, DefaultProjector
  • Wrong role for a builtin: list and type are classes and callable is a function, so :py:func:list and `:py:class:`callable didn't resolve.
  • Docstring lines napoleon read as types:
    • Get or set the depth mask (default: ...)
    • an argument missing its colon (path Path to...)
    • two pan: descriptions with "and" inside parentheses
  • Things with no API page (backend classes, arcade.gl.backends, arcade.gui.experimental as a module) are now plain literals instead of dead links.

New API pages

These public modules and classes had no pages, so references to them could never resolve:

  • Input Manager (arcade.input), which the advanced input guide links to
  • Hexagon Grids (arcade.hexagon), which the hex map tutorial links to
  • Compute Shader (arcade.gl.compute_shader.ComputeShader), added to the OpenGL pages
  • RenderTargetTexture, added to the Future Features page

Including InputManager's docstring surfaced a broken list and a link to a label that doesn't exist, so I fixed both.

Left for the second PR

These come from type annotations in signatures, not from docstring text:

  • Path and tuple[float
  • the sh.SpatialHash annotations in sprite_list.py
  • the StyleRef type variable
  • AllocatorException: pyglet's published docs are for 2.1, where it lives at pyglet.image.atlas

Testing

  • The docs build with -W passes.
  • A nitpicky build shows 10 real broken references, down from 161, and no new warnings of other kinds.
  • ruff, mypy and the full test suite (1840) pass.

🤖 Generated with Claude Code

A nitpicky Sphinx build found about 160 references that went nowhere:
typos, renamed or removed names, short names Sphinx can't find, roles
that don't match the target (list and type are classes, callable is a
function), and docstring lines napoleon misread as types. Most now point
at the documented name; ones that have no page become plain literals.

The hexagon and input modules, ComputeShader and RenderTargetTexture
had no API pages, so references to them couldn't resolve. Adds those.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@pvcraven
pvcraven merged commit 55499d7 into development Oct 9, 2026
7 checks passed
@pvcraven
pvcraven deleted the fix-doc-references branch October 9, 2026 17:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant