From cba8197b42282b376865be3b5ffc94dd7de45cf2 Mon Sep 17 00:00:00 2001 From: Paul V Craven Date: Fri, 9 Oct 2026 13:54:02 -0500 Subject: [PATCH] Link type in docs signatures to Python's type When an annotation names a class Sphinx can't find, it falls back to attributes whose names end with it, so type[W] linked to arcade.types.TiledObject.type. A Python domain subclass skips arcade's objects for type in signatures, so intersphinx links Python's. Co-Authored-By: Claude Opus 5.5 --- doc/conf.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/doc/conf.py b/doc/conf.py index 5d38e8afd..fbffe2e4e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -11,6 +11,7 @@ import sys from docutils import nodes +from sphinx.domains.python import PythonDomain from sphinx.util.docutils import SphinxRole HERE = Path(__file__).resolve() @@ -510,6 +511,21 @@ def _get_dir(app, path): generate_color_table(_get_dir(_app, "uicolor.py"), source) +class ArcadePythonDomain(PythonDomain): + """Sphinx's Python domain, except ``type`` in a signature links to Python's. + + When an annotation names a class Sphinx can't find, it falls back to + attributes with any name ending in that name, so ``type[W]`` linked to + :py:attr:`arcade.types.TiledObject.type`. Returning ``None`` lets + intersphinx link Python's ``type`` instead. + """ + + def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + if target == "type" and node.hasattr("refspecific"): + return None + return super().resolve_xref(env, fromdocname, builder, typ, target, node, contnode) + + def on_missing_reference(app, env, node, contnode): """Link a short name from SHORT_NAMES to its full name.""" full_name = SHORT_NAMES.get(node.get("reftarget")) @@ -585,6 +601,7 @@ def setup(app): app.connect("autodoc-process-bases", on_autodoc_process_bases) # Run before intersphinx, so it can resolve the full names of pyglet objects app.connect("missing-reference", on_missing_reference, priority=400) + app.add_domain(ArcadePythonDomain, override=True) # app.add_transform(Transform) app.add_role("resource", ResourceRole()) # Don't do anything that can fail on this event or it'll kill your build hard