Using Python docstring override and extend verbs in Sphinx

Question

I am using Sphinx to generate documentation from my docstrings, which are formatted in the Sphinx style. According to PEP-257 I should be using the verb "override" and "extend" to indicate if inherited methods are replaced or called.

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

As I am new to this it is not clear to me how I should do this in the Sphinx format. Do I simply use one of the words in my description or is there a key like :return: that I should apply? This instruction is given on the subclass level, is that where the verbs go or do I add them to the individual methods as well?

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

What would a simple but correct set of docstrings for class B and its methods look like?

score 2 · Accepted Answer · answered Oct 02 '20 at 03:46

One example straight from Python documentation is the defaultdict collection. It only overides one method of dictionary ( the __missing__(key) method).

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.

The documentation states this explicitly in prose, documents the overriden method, and explains the difference in parameters between superclass and subclasse constructor signatures.

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

What you call "key" is actually called a docstring section. There is no specific "docstring section" to indicate "override" or "extends", because that is implicit. If the subclass defines a method having the exact same name as a method of its superclass, that method is necessarily overriding or extending.

In conclusion, you'd be surprised to know your documentation is actually correct. At most you could add "overrides" and "extends" verbally together with a cross-reference to the superclass methods, like so:

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

You example lacks parameters in the signatures, the following answer shows how overloaded and extended methods having differing parameters can be documented.

Using Python docstring override and extend verbs in Sphinx

1 Answers1