Sphinx：记录与参数相同的属性

Question

我想用 numpy 风格的文档字符串来记录这样的东西。

class X(object):
    """ X

    Marble Counter

    Parameters
    ----------
    n_marbles : int
        an indicator of degree of madness

    Attributes
    ----------
    n_marbles : int
        an indicator of degree of madness
    """
    def __init__(n_marbles):
        self.n_marbles = n_marbles

属性和参数相同。 Can/should我避免重复？

Answer 1

对于像您这样的情况，输入参数和属性是完全相同的引用，我只会记录属性。熟悉Python的人马上就会知道参数是.

对于更复杂的情况，我更喜欢记录 class 本身和 __init__ 方法。在这种情况下，参数描述将进入 __init__ 的文档字符串。

由于您似乎在使用 autodoc 扩展，因此您需要在 autoclass 指令中添加一个 :special-members: __init__ 选项。如果要记录其他特殊成员，可以将它们添加到选项的参数列表中。您也可以完全省略 :special-members: 的参数以记录所有魔术属性，但这可能包括您不想要的内容，例如 __weakref__.

Sphinx：记录与参数相同的属性

Sphinx: Document an attribute that is same as a parameter

python

restructuredtext

python-sphinx