Question

我正在尝试遵循 Google 文档字符串样式，但是当存在添加/更新属性的函数时，我不确定如何记录函数（以及类本身）。目前我有这样的事情：

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 与 sphinx_rtd_theme 和 sphinx.ext.napoleon 扩展）。由于我在类和 __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

仅添加/更新类属性的类函数的文档字符串？

2 个答案: