Docstring for attributes

[Toni Barth]

Hello group,


i'm in the process of writing a sphinx-based documentation for a
Cython-based package right now and noticed that it seems to be the case
that attribute docstrings don't get properly added when building
extension types, although method and property docstrings work just fine.


I noticed that support for public attribute docstrings was added here
(https://github.com/cython/cython/issues/766), but my attributes are
readonly, so still important to the public, but just not writable. I
don't know if this has something to do with this issue/feature though,
but my docstring simply doesn't get copied over.


I've got a pxd file with my class definition and a .pyx file, which
looks like this:


foo.pxd:


cdef class foo:

  cdef readonly Version api_version
  cdef readonly Version version


foo.pyx:


cdef class foo:

  def __cinit__(foo self):

    self.api_version = Version(_API_VERSION)
    """
    the version this package was designed to work with.
    """

    self.version = Version(get_version())
    """
    version of the shared library currently loaded
    """


Version and api_version don't get properly annotated when using sphinx
autodoc, but they get detected properly. I tried annotating them
manually within the class docstring, but since they already got
detected, sphinx tells me that I now got two separate documentations for
the same attribute, which obviously is a problem.


Is there any way to properly annotate attributes (readonly if possible)
for sphinx to properly pick up?


Thanks.


Best Regards.


Toni Barth

[da-woods]

I'm pretty sure the docstring should go with the definition, not the
assignment. The current tests are at
https://github.com/cython/cython/blob/30fc474830b4a5beb88cdc53a31797ed794cddb8/tests/run/embedsignatures.pyx#L208.

The idea is that the docstring is a constant associated with the
attribute, which you may have multiple assignments and don't want to
reset the docstring each time.

I don't think docstrings in pxd files are specifically tested, so there
may be bugs there. But that's where I'd put them.

[Toni Barth]

Am 18.01.2021 um 21:55 schrieb da-woods:
> I'm pretty sure the docstring should go with the definition, not the
> assignment. The current tests are at
> https://github.com/cython/cython/blob/30fc474830b4a5beb88cdc53a31797ed794cddb8/tests/run/embedsignatures.pyx#L208.
>

Thanks, that did the trick. Moving it into the pxd file is not as nice
as i'd like it to be, but I guess its a compromise I can go with.


Do you know if there is any way to let sphinx automatically determine
the type of attributes and return type of methods and document them
properly? It doesn't show any type for attributes yet, nor does it
annotate return values of methods, just the parameters are properly
documented. Or is there a way I can format the docstrings so that the
type/return type is properly added to the generated docs?


Thanks.

[da-woods]

I know absolutely nothing about Sphinx I'm afraid. However, a guess:
Cython can use annotations to set the type, and I'd think those would be
the thing with the greatest change of also being understood by a
documentation generator.

I think correctly populating a classes's __annotations__ is a pretty
recent feature though so you may need to use a very up-to-date version.