Skip to content

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

Open
@david-cortes

Description

@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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions