WARNING: error while formatting signature: Handler <function process_signature at 0x00000280E14DCC10> for event 'autodoc-process-signature' threw an exception

[Timtam]

Hello,

i'm currently trying to use sphinx-autodoc-typehints to create a nice documentation for my project pyage (https://github.com/Timtam/pyage).
I do have an issue however. When i'm annotating a method like this:

    def quit(self) -> None:
        """
        This method will tell the game loop to quit as soon as possible, releasing all resources in the process.
    
        Parameters
        ----------


        Returns
        -------
        :obj:`None`

        """

sphinx-autodoc-typehints will fail with an indescriptive error when processing the signature of that method:
WARNING: error while formatting signature for pyage.app.App.quit: Handler <function process_signature at 0x00000280E14DCC10> for event 'autodoc-process-signature' threw an exception (exception: 'quit')

I've configured my sphinx-autodoc-typehints as follows:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.intersphinx",
    "sphinx.ext.todo",
    "sphinx.ext.viewcode",
    "sphinx.ext.napoleon",
    "sphinx_autodoc_typehints",
]

napoleon_use_param = True

Do you have any idea of what might cause this issue, or how I can help you digging deeper into the issue?

I'm running Python 3.8.2 with sphinx 3.3.1 and sphinx-autodoc-typehints 1.11.1.
Thanks.

[blueyed]

WARNING: error while formatting signature for pyage.app.App.quit: Handler <function process_signature at 0x00000280E14DCC10> for event 'autodoc-process-signature' threw an exception (exception: 'quit')

Looks like quit is throwing an exception, and somehow gets called during generating the documentation?
You can start by adding some __import__("traceback").print_stack() there, or import pdb; pdb.set_trace() etc to see where it gets done / is coming from.

[Timtam]

Thanks. I tried that and it gave me no output whatsoever, but I managed to find the troublemaker anyway.
My class is annotated with the singleton decorator from a package called py-singleton (https://pypi.org/project/py-singleton/).
As soon as I remove the decorator, everything works fine. I guess that thing messes my class up some way or another. I'll see if I can find something else to simplify my process of working with singletons which is more compatible with sphinx.

[Paebbels]

I have a similar behavior. For now I can tell it's related to using a metaclass other then type. I need to check if my meta class is an alternative implementation of a singleton (I have one in my code but not based in py-singleton).

---

/cc @umarcor

[gaborbernat]

A PR for this would we welcome.

[Paebbels]

I think a PR from me side is out of scope. I'm not a Sphinx / Sphinx extension developer and I have no knowledge about this particular extension nor why a meta class should break the code or cause such a hard error.

In addition, I tried multiple time to debug Sphinx code, but it's just a nightmare how it's programmed and documented. It's still a nice tools and it works, but fixing problems in Sphinx is a nightmare as it has no clear and documented software architecture.

Sorry.

---

If you like, I can try to make a minimal example and also try to narrow it down.

[gaborbernat]

Any project that replicates the issue would be a great help 👍 though note, if you're not willing to make a PR progress on this, would be slower as this is one of many projects I maintain and my free time is severely limited.

[Paebbels]

@gaborbernat I know this situation as I'm also involved in >40 projects - in many of them as maintainer :)

Anyhow, I'll provide a minimal reproducer for investigations. Since a while I have it on my todo list. I just accidently found this issues. Until a few days ago, I though I'm alone with this problem and it might be due to other extensions or special code I'm using. So with this open issue, I have a first idea how to narrow it down.

[StephanAkkerman]

Still relevant, using Sphinx for a Discord bot seems quite hard now as almost every function uses a decorator.

[gaborbernat]

A PR for this would we welcome.

👍

[StephanAkkerman]

I just tested it and the error is also shown by only running the conf.py file using extensions = "sphinx.ext.autodoc". I assume sphinx_autodoc_typehints depends on that, right? As when using extensions = "sphinx_autodoc_typehints" the same error is also shown.

[moi90]

This seems to be resolved in sphinx-autodoc-typehints 2.1.1.

However, this version is not yet on PyPI. When will it be published? (@gaborbernat)