autodoc: fix crash when a signature handler returns a signature for a data object

CHANGES.rst

@@ -13,6 +13,11 @@ Bugs fixed
   English stemmer) and Dutch (which uses the Dutch Porter stemmer).
   Patch by Hugo van Kemenade
 
+* #14576: autodoc: Fix a crash (``list assignment index out of range``)
+  when an ``autodoc-process-signature`` event handler returns a
+  replacement signature for an object without one (e.g. a callable
+  data object).
+
 
 Release 9.1.0 (released Dec 31, 2025)
 =====================================

sphinx/ext/autodoc/_dynamic/_signatures.py

@@ -125,7 +125,14 @@ def _format_signatures(
     ):
         if len(result) == 2 and isinstance(result[0], str):
             args, retann = result
-            signatures[0] = (args, retann if isinstance(retann, str) else '')
+            signature = (args, retann if isinstance(retann, str) else '')
+            if signatures:
+                signatures[0] = signature
+            else:
+                # Some objects (e.g. data objects) never have a signature, but
+                # an event listener may still provide a replacement one.
+                # (https://github.com/sphinx-doc/sphinx/issues/14576)
+                signatures.append(signature)
 
     if props.obj_type in {'module', 'data', 'type'}:
         signatures[1:] = ()  # discard all signatures save the first

tests/test_ext_autodoc/test_ext_autodoc_signatures.py

@@ -16,7 +16,7 @@
 from sphinx.ext.autodoc._shared import _AutodocConfig
 from sphinx.util.inspect import safe_getattr
 
-from tests.test_ext_autodoc.autodoc_util import FakeEvents
+from tests.test_ext_autodoc.autodoc_util import FakeEvents, do_autodoc
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -289,6 +289,24 @@ def foo1(self, b, *c):  # type: ignore[no-untyped-def]
     assert format_sig('method', 'bar', H.foo1, events=events) == ('42', '')
 
 
+@pytest.mark.usefixtures('inject_autodoc_root_into_sys_path')
+def test_data_object_signature_from_event_handler() -> None:
+    # https://github.com/sphinx-doc/sphinx/issues/14576
+    # Data objects never get a signature, but an ``autodoc-process-signature``
+    # listener may still provide a replacement one. That replacement must be
+    # appended rather than crashing on ``signatures[0]`` assignment.
+    def process_signature(app, what, name, obj, options, args, retann):
+        if what == 'data':
+            return '()', None
+        return None
+
+    events = FakeEvents()
+    events.connect('autodoc-process-signature', process_signature)
+
+    content = do_autodoc('data', 'target.callable.function', events=events)
+    assert '.. py:data:: function()' in content
+
+
 def test_format_functools_partial_signatures() -> None:
     # test functions created via functools.partial
     from functools import partial