One source of frustration I've run into when using Sphinx to document Python projects is this: out-of-the-box, Sphinx's py domain has directives for function, method, staticmethod, classmethod, decorator, and decoratormethod. But this leaves a bunch of common Python types that it doesn't support: async functions/methods, abstract functions/methods, context managers, async context managers, generators, async generators, and combinations of the above.

This is particularly annoying for new projects using async/await, since this is a critical part of function signatures in the language now, and Sphinx has no standard way to handle it. But what makes it extra tricky is that the async/not-async distinction is orthogonal to other distinctions like regular method/staticmethod/classmethod. Recently I found myself trying to document an abstract async classmethod, which drove home the limitations of the current system :-).

My solution was to write sphinxcontrib-trio, which is an extension that – instead of trying to add a dozen+ new directives for every possible method type – replaces the standard py:function and py:method with new versions that take options describing the different attributes of the function/method. So that abstract async classmethod is just:

.. method::
   :abstractmethod:
   :async:
   :classmethod:

Doing this via an extension is convenient because it makes the functionality available immediately. But as far as I can tell, this approach is a 100% backwards compatible extension that makes the py domain much more usable for modern Python projects. So I'm wondering: is there any interest in building this functionality into Sphinx itself?