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?
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