New autodoc logic prevents necessary patches

[kasium]

Describe the bug

With sphinx 8 it was possible to let autodoc document class-based decorators doing some magic, like invoke.task. This was possible by just adding another documenter using add_autodocumenter as you can see in https://github.com/SAP/invoke-plugin-for-sphinx/blob/main/invoke_plugin_for_sphinx/_plugin.py.

However, with sphinx 9 I need to patch a private function which is not very nice: https://github.com/SAP/invoke-plugin-for-sphinx/pull/236. Can you please support here?

How to Reproduce

n/a

Environment Information

Platform:              linux; (Linux-5.14.21-150500.55.124-default-x86_64-with-glibc2.31)
Python version:        3.14.0 (main, Nov 10 2025, 09:33:32) [GCC 7.5.0])
Python implementation: CPython
Sphinx version:        9.0.0
Docutils version:      0.21.2
Jinja2 version:        3.1.6
Pygments version:      2.19.2

Sphinx extensions

* sphinx.ext.autodoc

Additional context

No response

[AA-Turner]

Quoting myself from https://github.com/jbms/sphinx-immaterial/issues/475#issuecomment-3592277558

• You may want to enable autodoc_use_legacy_class_based for all users of your theme, at least initially.
• That option is intended to transparently use the 'legacy' implementation, although the files have moved to sphinx.ext.autodoc._legacy_class_based (may be relevant for monkeypatching).
• The new implementation uses a new _ItemProps class & a largely functional approach, contained in the new underscore-prefixed modules of autodoc. For ease of maintenence upstream I intend for the entire new implementation to be private, which may impact monkeypatching.
• I'm very open to changes in the new autodoc implementation to make things easier for sphinx-immaterial, or upstreamed patches etc. Also happy to consider e.g. new autodoc events.

Patches like the one you link have been a major problem in maintaining Sphinx/autodoc, so I want to find a way where we no longer need them.

Why is this patch needed, and what would be a good replacement for it?

A

[kasium]

So the problem the plugin tries to solve is the following. In invoke, python functions are decorated with @task. This decorator makes the function a class instance of invoke.Task. As it's now an instance, autodoc ignores it which is not great. With my plugin, I just tell autodoc - "Hey, that is a function" - and so it's documented as expected