Mit Python docstring können Sie Verben in Sphinx überschreiben und erweitern
Ich verwende Sphinx, um Dokumentation aus meinen Dokumentzeichenfolgen zu generieren, die im Sphinx-Stil formatiert sind . Gemäß PEP-257 sollte ich das Verb "überschreiben" und "erweitern" verwenden, um anzuzeigen, ob geerbte Methoden ersetzt oder aufgerufen werden.
Wenn eine Klasse eine andere Klasse unterklassifiziert und ihr Verhalten größtenteils von dieser Klasse geerbt wird, sollte ihre Dokumentzeichenfolge dies erwähnen und die Unterschiede zusammenfassen. Verwenden Sie das Verb "override", um anzugeben, dass eine Unterklassenmethode eine Oberklassenmethode ersetzt und die Oberklassenmethode nicht aufruft. Verwenden Sie das Verb "verlängern", um anzugeben, dass eine Unterklassenmethode die Oberklassenmethode aufruft (zusätzlich zu ihrem eigenen Verhalten).
Da ich neu in diesem Bereich bin, ist mir nicht klar, wie ich dies im Sphinx-Format tun soll. Ich einfach eines der Worte in meiner Beschreibung Verwenden oder ist es ein Schlüssel wie , :return:dass ich anwenden soll? Diese Anweisung wird auf der Ebene der Unterklassen gegeben. Gehen die Verben dort hin oder füge ich sie auch den einzelnen Methoden hinzu?
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")
Wie würde ein einfacher, aber korrekter Satz von Dokumentzeichenfolgen class Bund deren Methoden aussehen?
Antworten
Ein Beispiel direkt aus der Python-Dokumentation ist die defaultdictSammlung. Es überschreibt nur eine Methode des Wörterbuchs (die __missing__(key)Methode).
defaultdict ist eine Unterklasse der integrierten dict-Klasse. Es überschreibt eine Methode (...) Die verbleibende Funktionalität ist dieselbe wie für die dict-Klasse und wird hier nicht dokumentiert. (...) Alle verbleibenden Argumente werden so behandelt, als ob sie an den dict-Konstruktor übergeben würden, einschließlich des Schlüsselworts Argumente.
In der Dokumentation wird dies explizit in der Prosa angegeben, die Überschreibungsmethode dokumentiert und der Unterschied in den Parametern zwischen Konstruktorsignaturen der Oberklasse und der Unterklasse erläutert.
Benutze ich einfach eines der Wörter in meiner Beschreibung oder ist dies ein Schlüssel wie: return: dass ich mich bewerben muss?
Was Sie "Schlüssel" nennen, wird eigentlich als Dokumentstring-Abschnitt bezeichnet . Es gibt keinen speziellen "docstring-Abschnitt" , der "überschreiben" oder "erweitern" angibt, da dies implizit ist. Wenn die Unterklasse eine Methode definiert, die genau denselben Namen wie eine Methode ihrer Oberklasse hat, wird diese Methode notwendigerweise überschrieben oder erweitert.
Abschließend wären Sie überrascht zu wissen, dass Ihre Dokumentation tatsächlich korrekt ist. Sie können höchstens "Überschreibungen" und "Erweiterungen" verbal zusammen mit einem Querverweis auf die Methoden der Oberklasse hinzufügen, wie folgt:
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")
In Ihrem Beispiel fehlen Parameter in den Signaturen. Die folgende Antwort zeigt, wie überladene und erweiterte Methoden mit unterschiedlichen Parametern dokumentiert werden können .