class 函数的文档字符串只有 adds/updates class 属性？

Question

我正在尝试遵循文档字符串的 Google 风格，但我不确定当函数 add/supdates 一个属性。目前我有这样的东西：

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

但我认为生成的文档（使用带有 sphinx_rtd_theme 和 sphinx.ext.napoleon 扩展名的 sphinx）。因为我在 class 和 __init__ 中都有文档字符串，所以我将 napoleon_include_init_with_doc 设置为 True。但同样，该文档看起来很笨拙且难以理解。我尝试在 Google 风格指南中找到最佳实践，但找不到好的指导。在这种情况下是否有最佳实践？

Answer 1

有一个可以遵循的通用格式。虽然在某些场景下，有必要脱离传统风格，但你的情况似乎是相当基本的。这是 Python:

中文档字符串的 PEP 约定指南

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

Answer 2

就像 Harsh Nagouda 发布的那样，似乎并没有真正的特定格式。我对 Sphinx 生成的文档的外观感到满意的解决方案将设置 napoleon_include_init_with_doc 设置为 False，文档字符串如下所示：

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

class 函数的文档字符串只有 adds/updates class 属性？

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

python

docstring

google-style-guide