0

我正在尝试遵循文档字符串的 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 扩展名）。由于我在 class 和 中都有 docstring，因此__init__我将 napoleon_include_init_with_doc 设置设置为 True。但同样，文档看起来很笨拙且难以理解。我尝试在 Google Style Guide 中找到最佳实践，但找不到好的指导。在这种情况下是否有最佳实践？

4

2 回答 2

0

有一个可以遵循的通用格式。虽然在某些场景下，需要摆脱传统的风格，但你的情况似乎还比较基本。这是 Python 中文档字符串的 PEP 约定指南：

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

于 2021-06-09T00:25:47.230 回答
0

就像 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
于 2021-06-15T15:29:48.480 回答