Docstring for class functions that only adds/updates class attributes?

Question

I'm trying to follow the Google Style of docstrings, but I'm not sure how to document a function (and the class itself) when there's functions that add/supdates an attribute. Currently I have something like this:

class myclass():
    """This is an example class

    Attributes: (Should I have this here?)
        att1 (float): Attribute 1
        att2 (float): Attribute 2
        att3 (float): Attribute 3
        att4 (float): Attribute 4
        att5 (float): Attribute 5
    """

    def __init__(self, param1, param2, param3=2.1):
        """Initializes attributes

        Args:
            param1 (float): First parameter.
            param2 (float): Second parameter.
            param3 (float, optional): Third parameter. Defaults to 2.1.
        """
        self.att1 = param1
        self.att2 = param2
        self.att3 = param3
        self.att4 = 3.2

    def func1(self, param1):
        """This function adds new attributes.

         (Do I add a Note: here saying that this function is creating att5?)

         Args:
             param1 (float): Parameter 1.
         """
        self.att5 = param1*3

But I think the resulting documentation (using sphinx with the sphinx_rtd_theme and the sphinx.ext.napoleon extension). Since I have docstring in both the class and the __init__, I set to True the napoleon_include_init_with_doc setting. But again, the documentation looks awkward and hard to follow. I tried fining a best practice in the Google Style Guide, but couldn't find good guidance. Is there a best practice in this case?

Answer 1

Like Harsh Nagouda posted, there seems there's not really a specific format. My solution, which I'm happy with on how the documents produced by Sphinx look, leaves the setting napoleon_include_init_with_doc set to False, and the docstrings look like:

class myclass():
    """This is an example class.

    Attributes:
        att1 (float): Attribute 1. It is an input to :class:`myclass`.
        att2 (float): Attribute 2. It is an input to :class:`myclass`.
        att3 (float): Attribute 3. Defaults to 2.1. It is an input to :class:`myclass`.
        att4 (float): Attribute 4. It is initialized when creating :class:`myclass`.
        att5 (float): Attribute 5. It is updated when running :meth:`func1`.
    """

    def __init__(self, param1, param2, param3=2.1):
        """Initializes attributes. (This docstring is for source code only, Sphinx will ignore this)

        Args:
            param1 (float): First parameter.
            param2 (float): Second parameter.
            param3 (float, optional): Third parameter. Defaults to 2.1.
        """
        self.att1 = param1
        self.att2 = param2
        self.att3 = param3
        self.att4 = 3.2

    def func1(self, param1):
        """This function adds new attributes.

        Adds/updates the following attributes:

        - :attr:`att5`

         Args:
             param1 (float): Parameter 1.
         """
        self.att5 = param1*3

Answer 2

There is a general format that can be followed. Although in certain scenarios, it becomes necessary to break away from the traditional style, your situation seems to be fairly basic. Here is a PEP convention guide for docstrings in Python:

https://www.python.org/dev/peps/pep-0257/