Usando Python docstring anular y extender verbos en Sphinx

Question

Estoy usando Sphinx para generar documentación a partir de mis cadenas de documentos, que están formateadas al estilo Sphinx . De acuerdo con PEP-257 , debería usar el verbo "anular" y "extender" para indicar si los métodos heredados se reemplazan o se llaman.

Si una clase subclasifica a otra clase y su comportamiento se hereda principalmente de esa clase, su cadena de documentos debe mencionar esto y resumir las diferencias. Use el verbo "anular" para indicar que un método de subclase reemplaza a un método de superclase y no llama al método de superclase; use el verbo "extender" para indicar que un método de subclase llama al método de superclase (además de su propio comportamiento).

Como soy nuevo en esto, no me queda claro cómo debo hacerlo en el formato Sphinx. ¿Utilizo simplemente una de las palabras en mi descripción o hay una clave como :return:esa que debería aplicar? Esta instrucción se da en el nivel de subclase , ¿es ahí donde van los verbos o también los agrego a los métodos individuales?

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

¿Cómo sería un conjunto simple pero correcto de cadenas de documentos class By sus métodos?

Answer 1

Un ejemplo directamente de la documentación de Python es la defaultdictcolección. Solo anula un método de diccionario (el __missing__(key)método).

defaultdict es una subclase de la clase dict incorporada. Anula un método (...) La funcionalidad restante es la misma que para la clase dict y no se documenta aquí. (...) Todos los argumentos restantes se tratan de la misma manera que si se hubieran pasado al constructor dict, incluida la palabra clave argumentos.

La documentación establece esto explícitamente en prosa, documenta el método anulado y explica la diferencia en los parámetros entre las firmas de constructores de superclase y subclase.

¿Utilizo simplemente una de las palabras en mi descripción o es una clave como: retorno: que necesito aplicar?

Lo que llama "clave" en realidad se llama una sección de cadena de documentos . No hay una "sección de cadena de documentos" específica para indicar "anular" o "extender", porque eso está implícito. Si la subclase define un método que tiene exactamente el mismo nombre que un método de su superclase, ese método necesariamente prevalecerá o se extenderá.

En conclusión, le sorprendería saber que su documentación es realmente correcta. A lo sumo, podría agregar "anulaciones" y "extensiones" verbalmente junto con una referencia cruzada a los métodos de superclase, así:

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

Su ejemplo carece de parámetros en las firmas, la siguiente respuesta muestra cómo se pueden documentar los métodos sobrecargados y extendidos que tienen parámetros diferentes .