Embedded signature doc behavior for classes different from regular Python

[david-cortes]

When creating a Python class, if I put docstrings under the class name or under __init__, these would show up, respectively, under class.__doc__ and class.__init__.__doc__, e.g.:

class cl:
	"""ds1"""
    def __init__(self, a=1):
        """ds2"""
        self.a = a

cl.__doc__ == "ds1"
cl.__init__.__doc__ == "ds2"

Usually, documentation is picked by other tools from the __init__ part, so that's where it's usually put, and in such case class.__doc__ will be empty (Python None).

But with Cython classes having embedded signatures, if I put a docstring under __init__, it will still generate a non-empty class.__doc__, which will contain the function arguments but not the rest, e.g.

cimport cython
@cython.embedsignature(True)
cdef class cl:
	cdef int a
	def __init__(self, a = 1):
		"""ds"""
		self.a = a

cl.__doc__ == "cl(a=1)"
cl.__init__.__doc__ == "ds"

(And if I don't put it, it wouldn't document the arguments)

Would be nice if documentation would work the same as in regular Python (i.e. don't create class.__doc__ if the docstring is under __init__), as it makes it easier for the documentation to work with other tools. For example, sphinx will by default look for __doc__ first, so in this case it ends up (by default) showing only the function call documentation and not the user docstring.

[scoder]

Sounds good. PR welcome that prefers the place that already has a docstring. See the EmbedSignature transform.

[david-cortes]

A word of warning for whoever tries to work on this: it seems after making the class.__doc__ entry None and the class.__init__.__doc__ entry to hold the docstring instead, sphinx would not show either on the documentation through autodoc.

This is what I tried but I'm not sure if there are still other differences in terms of the internal Python documentation through help(class) before and after the changes - changed this part in AutoDocTransforms.py:

if signature:
	if is_constructor:
		doc_holder = self.class_node.entry.type.scope
	else:
		doc_holder = node.entry

to this:

if signature:
	if not is_constructor or not self.class_node.entry.type.scope.doc:
		doc_holder = node.entry
	else:
		doc_holder = self.class_node.entry.type.scope

Putting the docstring under both seems to accomplish the purpose of having it show in sphinx and IDEs, but it doesn't seem an elegant solution.