在 Sphinx 中使用 Python 文档字符串覆盖和扩展动词

Question

我正在使用 Sphinx 从文档字符串生成文档，文档字符串的格式为Sphinx style。根据PEP-257，我应该使用动词“覆盖”和“扩展”来指示继承的方法是否被替换或调用。如果一个类是另一个类的子类，并且它的行为主要是从该类继承的，那么它的文档字符串应该提及这一点并总结差异。使用动词“override”表示子类方法替换超类方法并且不调用超类方法；使用动词“extend”来指示子类方法调用超类方法（除了它自己的行为之外）。由于我对此很陌生，因此我不清楚应该如何以 Sphinx 格式执行此操作。我是否只使用描述中的某个词，或者是否有一个类似的键:return:我应该应用？该指令是在子类级别给出的，是动词所在的位置还是我也将它们添加到各个方法中？class A:    """This is my base class."""    def method_a(self):        """My base method a."""        pass    def method_b(self):        """My base method b."""        passclass B(A):    """This is the subclass that inherits from :class: A."""    def method_a(self):        """This method replaces the inherited method_a."""        print("overridden")    def method_b(self):        """This method calls the inherited method_b."""        super(B, self).method_b()        print("extended")一组简单但正确的文档字符串及其class B方法会是什么样子？

Answer 1

直接来自 Python 文档的一个示例是defaultdict集合。它仅覆盖字典的一种方法（__missing__(key)方法）。

defaultdict 是内置 dict 类的子类。它重写一种方法 (...) 其余功能与 dict 类相同，此处未记录。(...) 所有剩余参数的处理方式与传递给 dict 构造函数的方式相同，包括关键字论据。

该文档以散文形式明确说明了这一点，记录了重写方法，并解释了超类和子类构造函数签名之间的参数差异。

我是否只使用描述中的某个单词，或者这是我需要应用的像 :return: 这样的键？

你所说的“key”实际上被称为文档字符串部分。没有特定的“文档字符串部分”来指示“覆盖”或“扩展”，因为这是隐式的。如果子类定义的方法与其超类的方法具有完全相同的名称，则该方法必然是重写或扩展的。

总之，您会惊讶地发现您的文档实际上是正确的。您最多可以口头添加“覆盖”和“扩展”以及对超类方法的交叉引用，如下所示：

class B(A):

    """Neither method_a nor method_b are inherited.

       Both methods are redefined in this class.

    """

    def method_a(self):

        """This method overrides :meth:`A.method_a`."""

        print("overridden")

    def method_b(self):

        """This method extends :meth:`A.method_b`."""

        super().method_b()

        print("extended")