0

How are instance and class attributes correctly documented in Python when using reStructredText docstrings? I have the following example class:

class TestClass(object):
    """ This is a test class to demonstrate documentation.

    :param first_name: first name of the person
    :type first_name: str
    :param last_name: last name of the person
    :type last_name: str

    :param name: full name of the person
    :type name: str

    :cvar species: species of the person
    :type species: str
    """

    species = 'human'

    def __init__(self, first_name, last_name):
        self.name = ' '.join((first_name, last_name))

I already know that I should document the functionality of the __init__ function in the class docstring, including it's parameters first_name and last_name. But what about the instance attribute name and the class attribute species?

The goal is to show the documentation correctly in PyCharm and to have the code compatible with Sphinx and other docstring parsers. This is how PyCharm is currently displaying the documentation. Parameters are shown correctly, but the description for the attributes are missing.

Class documentation in PyCharm

init documentation in PyCharm

class attribute documentation in PyCharm

instance attribute documentation in PyCharm

erik
  • 619
  • 1
  • 11
  • 20
  • `:param name: full name of the person` does not look right. It should be `:ivar name: full name of the person`. Also, the indentation in the code sample is bad. – mzjn Feb 08 '22 at 09:07
  • Indentation got messed up when copying in the code. Fixed it. – erik Feb 08 '22 at 09:14
  • With ```ivar``` PyCharm at least doesn't throw a warning in the docstring. However, it still doesn't show the documentation of this attribute anywhere. Is this just a shortcoming of PyCharm's docstring parser? – erik Feb 08 '22 at 09:16
  • Yes it does. A shame PyCharm doesn't support those class and instance attributes. I didn't get around to testing if they are correctly recognized by Sphinx. – erik Feb 23 '22 at 05:32

0 Answers0