Sphinx：记录与param相同的属性

Question

我想用numpy样式的docstring来记录类似的东西。在

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

属性和参数是相同的。我能/应该避免重复吗？在

Answer 1

对于像您这样的情况，输入参数和属性是完全相同的引用，我只记录属性。任何熟悉Python的人都会立即知道参数是。在

对于更复杂的情况，我更喜欢记录类本身和__init__方法。在本例中，参数描述将进入__init__的docstring中。在

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