Pretty-print magic methods.

Motivation

When autodoc generates docs for magic methods like __str__ or __getitem__, it displays the method signatures the same way as for any other method. However, this is not how magic methods are typically used, and the literal names may not be the best way to document them.

Proposal

Instead of displaying the literal names of magic methods, display them as they would be used: for instance, len(self) instead of __len__(). This is what the Python documentation does for builtin types. It's possible to do this manually, as Python has, but it would be both more convenient and more consistent for it to be done by an optional feature or extension.

Selected Examples

Prior Art

The Python docs do this manually in some places, though they are inconsistent.

A library I'm working on does this with a custom extension. The implementation is rough, but perhaps it may suffice as a proof of concept.

Start by reviewing the requested signature transformations and the linked custom extension for its proof of concept. Then locate Sphinx's autodoc handling for Python method signatures and existing tests for autodoc output. Done means an optional, consistent presentation of the listed magic methods with coverage for representative cases.