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

Question

我正在使用 Sphinx 从我的文档字符串生成文档，这些文档的格式为 Sphinx style. According to PEP-257 我应该使用动词“override”和“extend”来指示继承的方法是否被替换或调用。

If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behavior).

由于我是新手，所以我不清楚应该如何以 Sphinx 格式执行此操作。我是简单地使用我的描述中的一个词，还是有一个像 :return: 这样的 key 我应该申请？此说明是在子类级别上给出的，是动词去哪里还是我也将它们添加到各个方法中？

class A:
    """This is my base class."""

    def method_a(self):
        """My base method a."""
        pass

    def method_b(self):
        """My base method b."""
        pass


class 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 is a subclass of the built-in dict class. It overrides one method (...) The remaining functionality is the same as for the dict class and is not documented here.(...) All remaining arguments are treated the same as if they were passed to the dict constructor, including keyword arguments.

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

Do I simply use one of the words in my description or is this a key like :return: that I need to apply?

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

总之，您会惊讶地发现您的文档实际上是正确的。至多你可以在超类方法中口头添加“overrides”和“extends”以及 cross-reference，如下所示：

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")

您的示例在签名中缺少参数，以下答案显示。

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

Using Python docstring override and extend verbs in Sphinx

python

docstring

python-3.x

python-sphinx