This fixes:
* Signatures defined by __new__
* Signatures defined by metaclasses
* Signatures defined by builtin base classes
All of these changes bring the sphinx docs inline with the behavior of `inspect.signature`.
Note that this changes autodoc to output `.. py:class: MyClass()` with parentheses even if no user-defined __init__ is present.
This is quite deliberate, as if no user-defined `__init__` is present the default is `object.__init__`, which indeed does not take arguments.
This takes advantage of the fact that in Python 3.6 and up, the __dict__ attribute of classes and modules is insertion-ordered, which is usually a good approximation of "source order".
Notably, this means that `..automodule:: some_c_extension_module` will document members in the order they were added to the module dict, which is likely what the user wants.
This `if not self._datadescriptor` was originally here before type annotations were supported, to prevent showing `descr4 = <_Descriptor ...>` in the docs.
When type annotations were added, the support for appending `:type:` was put in the wrong place.
It should have been outside this if, not within it.
A common use case for this is a class like `namedtuple`, which has a public `_replace` method that is so-named in order not to conflict with arbitrary user-provided attributes.
Rejected spellings include:
* `:meta not-private:`
* `:meta private: False`
term_decode is documented as `(unicode) -> unicode`, but actually:
* Accepts `bytes` arguments, despite not being documented to
* Returns `bytes` when it shouldn't
This is extracted from the more controversial #3584
Eric Wieser