Constructor and class docstrings are a mess

[tovrstra]

Cython and Sphinx are not compatible with the following recommendation from PEP257 (https://www.python.org/dev/peps/pep-0257):

The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.

This stops us (and probably many others) from write nice API documentation. Two problems should be fixed externally:

1. In Cython, the embedsignature flag should assign the signature of __init__ to the docstring of __init__, not the class docstring (which is the behavior in 0.24, the latest version at the time of writing). See https://groups.google.com/forum/#!searchin/cython-users/embedsignature/cython-users/sXtBF2nh5RI/GjcirKOWqBcJ. It would also be nice if __init__ could get the docstring of __cinit__ if the former is not defined.

2. Sphinx does not have a nice way of handling class and constructor docstrings in general (both for python and cython codes). There should be a autoclass_content="explicit" option that results in separated docstrings for the class and the constructor.