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

问题描述

我正在使用Sphinx从我的文档字符串生成文档，这些文档字符串以Sphinx style格式格式化。根据{{​​3}}，我应该使用动词“ override”和“ extend”来指示是否替换或调用了继承的方法。

如果一个类继承了另一个类，并且其行为大部分是从该类继承的，则其文档字符串应提及这一点并总结差异。使用动词“ override”来表示子类方法代替了超类方法，并且不调用超类方法；使用动词“ extend”表示子类方法（除了其自身的行为之外）还会调用超类方法。

由于我是新手，因此我不清楚如何以Sphinx格式执行此操作。我是在描述中简单地使用其中一个词还是应该使用:return:之类的 key ？该指令是在 subclass 级别上给出的，是动词到达的位置还是我也将它们添加到各个方法中？

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的一组简单而正确的文档字符串及其方法将是什么样？

解决方法

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

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

文档在散文中对此进行了明确说明，记录了重写方法，并解释了超类和子类构造函数签名之间的参数差异。

我只是在描述中使用其中一个单词，还是像：return：这样的密钥需要我申请？

您所谓的“键”实际上称为docstring section。没有特定的“文档字符串部分” 表示“覆盖”或“扩展”，因为这是隐式的。如果子类定义的方法与其父类的方法具有完全相同的名称，则该方法必然会覆盖或扩展。

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

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

您的示例在签名中缺少参数，以下答案显示how overloaded and extended methods having differing parameters can be documented。