autodoc: fix IndexError when an event handler supplies a signature

[UlikGames]

Fixes #14576

Previously, _format_signatures would run into trouble when it received an empty signatures list - something that naturally occurs with data, modules, type aliases, and attributes, since _get_signature_object doesn’t process these types.

When a custom event handler supplied a signature for one of these items, the code tried to update the first entry using signatures[0] = .... But if the list was empty, this triggered an IndexError, resulting in a warning and leaving both signature and docstring ungenerated.

This update replaces that approach with signatures[:1] = ..., a more flexible method that either adds the signature when the list is empty or replaces the first item if one exists - handling both cases smoothly.

Also worth noting: while the original report pointed to annotated class variables, they may not be the core issue. The same problem can occur with objects that have no annotations at all, or when a signature is provided via an event handler for something that previously had none.

New tests covering data, modules, type aliases, and attributes have been included, and everything runs successfully in local testing.

AI usage disclosure

Tool used: Claude Opus 5
How it was used: to run all of the tests, helping us ensure everything worked smoothly
Tool used: Codex Sol 5.6
How it was used: to refine the grammar and make the pull request description clearer.

After suggestion from @jdillard asked(which I truly appreciated), I took the time to rewrite the description personally.

[jdillard]

Closing until the PR description is updated in accordance with the AI policy, which is intended to ensure appropriate human oversight. I can reopen once the description is updated.

[ipilcher]

FWIW, I was getting the same error message when using this autodoc-process-signature hook with the dynamic autodoc path (or autosummary).

def add_pep695_generics_to_signature(
    app, obj_type, name, obj, options, signature, return_annotation
):
    if (
        obj_type in ('class', 'function', 'method')
        and hasattr(obj, "__type_params__")
        and len(obj.__type_params__) > 0
    ):
        params = f"[{', '.join(p.__name__ for p in obj.__type_params__)}]"
        if signature is not None:
            signature = params + signature
        else:
            signature = params + '()'
    return signature, return_annotation

With this change the error is gone and the hook works.

[larsoner]

I opened a similar PR in #14592 , I think the tests from there could be ported over here!

[UlikGames]

I opened a similar PR in #14592 , I think the tests from there could be ported over here!

Thanks, I ported the missing test case from #14592 in 357cdcb.

The full signature test file passes locally with 20 tests, and Ruff lint and format checks also pass.

[jdillard]

Thanks for adding the built-in case from #14592

[larsoner]

Same fix in principle as mine but simpler and has a superset of my tests, +1 for merge from me!