Utilisation du remplacement de la docstring Python et de l'extension des verbes dans Sphinx

Question

J'utilise Sphinx pour générer de la documentation à partir de mes docstrings, qui sont formatés dans le style Sphinx . Selon PEP-257, je devrais utiliser les verbes "override" et "extend" pour indiquer si les méthodes héritées sont remplacées ou appelées.

Si une classe sous-classe une autre classe et que son comportement est principalement hérité de cette classe, sa docstring devrait le mentionner et résumer les différences. Utilisez le verbe «override» pour indiquer qu'une méthode de sous-classe remplace une méthode de superclasse et n'appelle pas la méthode de superclasse; utilisez le verbe "extend" pour indiquer qu'une méthode de sous-classe appelle la méthode de superclasse (en plus de son propre comportement).

Comme je suis nouveau dans ce domaine, je ne vois pas clairement comment je dois faire cela au format Sphinx. Dois-je simplement utiliser l'un des mots dans ma description ou y a-t-il une clé comme :return:celle que je devrais appliquer? Cette instruction est donnée au niveau de la sous - classe , est-ce là que vont les verbes ou est-ce que je les ajoute également aux méthodes individuelles?

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

À quoi ressemblerait un ensemble simple mais correct de docstrings class Bet ses méthodes?

Answer 1

Un exemple tiré directement de la documentation Python est la defaultdictcollection. Il ne remplace qu'une seule méthode de dictionnaire (la __missing__(key)méthode).

defaultdict est une sous-classe de la classe dict intégrée. Il remplace une méthode (...) La fonctionnalité restante est la même que pour la classe dict et n'est pas documentée ici. (...) Tous les arguments restants sont traités de la même manière que s'ils étaient passés au constructeur dict, y compris le mot clé arguments.

La documentation le déclare explicitement en prose, documente la méthode surchargée et explique la différence de paramètres entre les signatures de constructeur de superclasse et de sous-classe.

Dois-je simplement utiliser l'un des mots dans ma description ou est-ce une clé comme: return: que je dois appliquer?

Ce que vous appelez "clé" est en fait appelé une section docstring . Il n'y a pas de "section docstring" spécifique pour indiquer "override" ou "extend ", car c'est implicite. Si la sous-classe définit une méthode ayant exactement le même nom qu'une méthode de sa superclasse, cette méthode est nécessairement redéfinie ou étendue.

En conclusion, vous seriez surpris de savoir que votre documentation est en fait correcte. Tout au plus, vous pouvez ajouter des «substitutions» et «étend» verbalement avec une référence croisée aux méthodes de la superclasse, comme ceci:

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

Votre exemple manque de paramètres dans les signatures, la réponse suivante montre comment les méthodes surchargées et étendues ayant des paramètres différents peuvent être documentées .