Turn on nitpicky mode for the docs

[pvcraven]

Closes #2297. Part 2, after #2969 fixed the broken references.

nitpicky = True makes Sphinx warn about every reference it can't resolve. CI's docs build uses -W, so a new broken link now fails the build. With this PR the nitpicky build has 0 warnings, down from about 275 after #2969.

What the remaining warnings were, and how they're handled (doc/conf.py)

• Type variables (about 146): SpriteType, W, T, P and similar in generic signatures. They aren't documented, so nitpick_ignore_regex skips them. It also skips private names (leading underscore) that show up in signatures.
• Short names in annotations (about 70): Controller, Vec2, Mat4, Point2, RGBA255 and others. Modules import these only for type checking, so Sphinx sees the bare name. A small missing-reference handler maps each one in SHORT_NAMES to its full name. Sphinx resolves arcade's own names, and intersphinx resolves the other libraries'. I tried autodoc_type_aliases first, but it produced TypeAliasForwardRef references instead.
• pyglet (about 50):
  • The intersphinx link pointed at pyglet's "latest" docs, which are pyglet 2.1. It now points at their development docs, which are pyglet 3, the version Arcade uses.
  • References now use pyglet 3 names: media.player.Player → AudioPlayer, graphics.Batch / Group → graphics.draw.Batch / Group, shapes.Circle is a class, TextLayout.content_width is a property, and the atlas raises pyglet.graphics.atlas.AllocatorException.
  • Bare pyglet and pyglet.gl have no module pages in pyglet's docs, so those mentions are plain text now.
  • pyglet.media.codecs.MediaDecoder isn't in pyglet's docs at all, so it's on nitpick_ignore.
• Other libraries:
  • Added intersphinx for pytiled_parser and typing_extensions.
  • pymunk.Shape.moment_of_inertia doesn't exist; the attribute is pymunk.Shape.moment.
  • Fixed the roles for itertools.chain (a function) and typing.Callable (data).
• Type aliases: the types page now documents Point, Point2, Point3, Point2List, RGBA255, RGBOrA255 and OneOrIterableOf, using the "data" option from Fail the docs build on quick index config problems #2967. Point's description had a line that started with # instead of #:, which dropped float from it.
• autodoc_preserve_defaults = True: UIManager.get_widgets_at(cls=UIWidget) rendered its default as <class 'arcade.gui.widgets.UIWidget'>. Sphinx couldn't parse that, so it split the signature at commas and broke tuple[float | int, float | int] apart. Defaults now show as written in the source, cls=UIWidget. This changed no other warnings.

Checked

• The docs build with -W has zero warnings.
• In the built docs I checked that:
  • Controller and Vec2 link to pyglet 3's docs
  • Point2 links to the types page
  • |pyglet Player| links to pyglet 3's AudioPlayer
  • get_widgets_at's signature renders correctly
  • Point's Color links to arcade's Color. The Color short name maps to pytiled_parser's, because that's what arcade.tilemap imports under the name, so I made Point name arcade's explicitly.
• ruff and mypy pass.

Found, not fixed here

type[...] in signatures links to arcade.types.TiledObject.type instead of Python's type. Sphinx's fuzzy name matching picks the attribute. Nitpicky mode can't catch it, because the link resolves.

🤖 Generated with Claude Code