Generic way to document "protocols" implemented by a Python class

[shimizukawa]

//Warning: grand ideas being braindumped ahead.//

It seems "unsphinxonic" to document special methods //directly//. Let's discuss alternatives. From the top of my head I can come up with these ideas:

• Reference a relevant ABC, even if not a direct subclass. For example, if my class has a __len__, I could have the equivalent of some variant of the following rst markup inserted either via some helper, or automatically, or manually according to a convention we invent:

  # !rst
  
  :provides: :class:`collections.Sized`

• One might want notes about the provided ABC beyond a mere marking of the fact. Perhaps instead it should be formatted more like a method, using the docstrings of the relevant protocol method(s)?

  //class// MySizable(foo, bar)

  //does// collections.Sized

  (__len__ docstring)

• Format the documentation for the relevant special method using the corresponding generic function. This sort of indirection in the documentation is already typical with Sphinx, in for example how it deals with __init__ by default.

  # !rst
  
  .. class:: MySizable
  
     .. method:: **len**
  
  ```
    The number of thingies in this thingy.
  ```

  Results in something like:

  //class// MySizable(foo, bar)

  len(MySizable)

  The number of thingies in this thingy.

  This suffers from the issue that the functions look like methods. An intrusive solution could be to change how methods are formatted, prefixing them with something like self., and similarly format the generic function calls like len(self) etc.

• Some special methods correspond to syntax rather than a generic function, so building on the previous point, documentation for specials like __call__, __getitem__ and __enter__ could be formatted using the corresponding syntax, similar to the py:decorator directives (but inferred from special methods):

  //class// MyMapping(foo, bar)

  self[item]

  Get the //item// from this mapping.

  //class// Flask()

  with self.test_request_context()

  Creates a WSGI environment from the given values.

  self(environ, start_response)

  The actual WSGI application.

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/745
• Originally reported by: Dag Odenhall
• Originally created at: 2011-08-04T16:45:49.045