如何使用 autodoc 覆盖 Sphinx 中的构造函数参数？答案

【问题标题】：How to override constructor parameters in Sphinx with autodoc?如何使用 autodoc 覆盖 Sphinx 中的构造函数参数？
【发布时间】：2012-12-09 08:58:55
【问题描述】：

假设我有这样的课程：

class MyClass(object):
    """ Summary docs for my class.

    Extended documentation for my class.
    """

    def __init__(self, *args):
        self.values = np.asarray(args)

如果我使用带有 autodoc 扩展名的 Sphinx 来记录此类：

.. automodule:: mymodule
   :members:

...构造函数签名显示为 MyClass(*args)。我宁愿覆盖它并将其记录为，例如，MyClass(first, second, third)。

如果这是一个函数，我可以覆盖文档字符串第一行中的签名。但是这个技巧似乎不适用于类文档字符串。那么如何覆盖构造函数签名呢？

【问题讨论】：

对我来说隐藏真正的呼叫签名听起来是个坏主意。
@LevLevitsky - 构造函数总是使用一定数量的参数调用。无论是*args 还是arg1, arg2, ... 都是一个实现细节，并且可能随时更改。没有“真正的”调用签名——用户应该传入记录在案的可接受参数。
行为有所不同（例如，对过多的争论）。
@LevLevitsky - 如果有人以未定义的方式使用 API（例如，传入过多的参数），我真的不在乎。我当然不认为有间接和混乱的文档是值得的。

标签： python python-sphinx autodoc

【解决方案1】：

我认为对你来说最好的选择是做这样的事情：

.. automodule:: mymodule
    :members:
    :exclude-members: MyClass

    .. autoclass:: MyClass(first, second, third)

MyClass 的参数将被覆盖，mymodule 的其他成员将被自动记录。您需要使用:exclude-members: 排除MyClass，因为它将被包含两次。我认为这是目前最简单的解决方案。

【讨论】：

我正在使用.. automodule:: mymodule \n :members: 技术。