Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Embedded signature doc behavior for classes different from regular Python #2876

Open
david-cortes opened this Issue Mar 2, 2019 · 2 comments

Comments

Projects
None yet
2 participants
@david-cortes
Copy link

david-cortes commented Mar 2, 2019

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

This comment has been minimized.

Copy link
Contributor

scoder commented Mar 2, 2019

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

@david-cortes

This comment has been minimized.

Copy link
Author

david-cortes commented Mar 7, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.