Link zur Klassenmethode in Python Docstring

87

Ich möchte einen Link zu einer Methode in meiner Klasse aus der Dokumentzeichenfolge einer anderen Methode derselben Klasse hinzufügen. Ich möchte, dass der Link in Sphinx und vorzugsweise auch in Spyder und anderen Python-IDEs funktioniert.

Ich habe mehrere Optionen ausprobiert und nur eine gefunden, die funktioniert, aber es ist umständlich.

Angenommen, die folgende Struktur in mymodule.py

def class MyClass():
    def foo(self):
        print 'foo'
    def bar(self):
        """This method does the same as <link to foo>"""
        print 'foo'

Ich habe folgende Optionen ausprobiert für <link to foo>:

  • : func: `foo`
  • : func: `self.foo`
  • : func: `MyClass.foo`
  • : func: `mymodule.MyClass.foo`

Der einzige, der effektiv einen Link erzeugt, ist: func: `mymodule.MyClass.foo`, aber der Link wird als angezeigt mymodule.MyClass.foo()und ich möchte einen Link, der als foo()oder angezeigt wird foo.
Keine der oben genannten Optionen erzeugt einen Link in Spyder.

Danke für Ihre Hilfe.

saroele
quelle
Was bedeutet "hinzufügen ... von innen" ??? Was ist der Unterschied zwischen einem Link und einem Hyperlink?
Eyquem
Ich ersetzt hyperlinkdurch linkum Verwirrung zu vermeiden.
Saroele
Ich verstehe Ihre Frage immer noch nicht sehr gut. Meinen Sie damit, dass Sie von Sphinx oder von Spyder oder von anderen Python-IDEs eine Abfrage der Dokumentzeichenfolge der Funktion durchführen möchten bar, die die Information "Die Funktion oder Methode, nach der Sie suchen, ist foo" liefert ?
Eyquem
Zweitens, welchen Unterschied machen Sie zwischen mymodule.MyClass.foo()und foo()? Und wie nennt man "Anzeige" ? Ist es die Anzeige einer Zeichenfolge? Oder möchten Sie ein Objekt zurückgeben? In diesem letzteren Fall sind die Paens am Ende mymodule.MyClass.foo()und foo()zu viel.
Eyquem
Entschuldigen Sie die Verwirrung, es ist immer schwierig, eine Frage kurz zu erklären. Ich möchte nur einen Link haben, auf den Sie klicken können, der Sie zum Dokumentstring von foo () führt (im Dokumentationsfenster der IDE oder im HTML-Build von Sphinx). In Bezug auf die Klammern: Sie sind korrekt :: func: mymodule.MyClass.fooführte dazu, dass der Link die Klammern enthielt. Und ich habe die Frage noch einmal leicht umformuliert.
Saroele

Antworten:

87

Die Lösung, die für Sphinx funktioniert, besteht darin, der Referenz das Präfix zu voranstellen ~.

Per Sphinx Dokumentation über Querverweise Syntax ,

Wenn Sie dem Inhalt ~ voranstellen, ist der Linktext nur die letzte Komponente des Ziels. Beispiel: py: meth: ~Queue.Queue.getverweist auf Queue.Queue.get, zeigt jedoch nur get als Linktext an.

Die Antwort lautet also:

class MyClass():
    def foo(self):
        print 'foo'
    def bar(self):
        """This method does the same as :func:`~mymodule.MyClass.foo`"""
        print 'foo'

Dies führt dazu, dass ein HTML wie folgt aussieht : This method does the same as foo(), und foo()ist ein Link.

Beachten Sie jedoch, dass dies in Spyder möglicherweise nicht als Link angezeigt wird.

saroele
quelle
15
( Spyder dev hier ) @saroele Ich plane, diese Situation in Zukunft zu verbessern. Ich stimme vollkommen zu, dass es wirklich cool wäre, es zu haben;)
Carlos Cordoba
Das ist wirklich toll und freue mich darauf. Vielen Dank für all Ihre Arbeit an Spyder!
Saroele
Sie können es mit der :any:Rolle tun - siehe den Hinweis zu default_setting.
naught101
1
Ist es möglich, Querverweise zu erstellen, ohne den vollständigen Modulpfad zu verwenden?
Jonathan
2
Stattdessen :func:fand ich, dass es sein muss :meth:.
Leo Fang
37

Wenn Sie den Text des Links manuell angeben möchten, können Sie Folgendes verwenden:

:func:`my text <mymodule.MyClass.foo>`

Weitere Informationen finden Sie unter Querverweise auf Python-Objekte .

devin_s
quelle
Das funktioniert, danke. Beim Betrachten des Links stellte ich fest, dass das Präfixieren der Referenz ~näher an dem liegt, was ich brauche. Ich habe das in einer separaten Antwort angegeben. Es funktioniert jedoch immer noch nicht in Spyder ...
Saroele
-4

Es scheint mir, dass Sie nur __name__oder __doc__zu Ihrem Ausdruck hinzufügen müssen, um zu erhalten, was Sie wollen.
Ich bin mir immer noch nicht sicher, ob ich das Ziel richtig verstanden habe

class MyClass():
    def foo(self):
        """I am the docstring of foo"""
        print 'foo'
    def bar(self):
        """This method does the same as <link to foo>"""
        print 'foo'

print
print MyClass.foo
print MyClass.foo.__name__
print MyClass.foo.__doc__
print
print MyClass.__dict__['foo']
print MyClass.__dict__['foo'].__name__
print MyClass.__dict__['foo'].__doc__

Ergebnis

<unbound method MyClass.foo>
foo
I am the docstring of foo

<function foo at 0x011C27B0>
foo
I am the docstring of foo
eyquem
quelle
1
Ich denke, Sie haben den Punkt der Frage verpasst: Ich möchte einen Link (Hyperlink) im HTML-Code meiner von Sphinx erstellten Dokumentation haben.
Saroele
Sie haben Recht, ich vermisse den Punkt. Und das liegt daran, dass ich Sphinx nicht kenne. Also habe ich versucht, Sphinx zu installieren. Aber es ist mir nicht gelungen. Ich bin unter Windows und habe versucht, Sphinx-Schnellstart zu verwenden, wie im Dokument angegeben. Aber ich glaube, ich habe ein Missverständnis des Installationsprozesses. Ich kann dir nicht helfen, sorry. Ich weiß nicht, was unter "Hyperlink" im Kontext von Sphinx zu verstehen ist.
Eyquem