Lien vers la méthode de classe dans docstring python


87

Je souhaite ajouter un lien vers une méthode de ma classe à partir de la docstring d'une autre méthode de la même classe. Je veux que le lien fonctionne dans sphinx et de préférence aussi dans Spyder et d'autres IDE Python.

J'ai essayé plusieurs options et n'en ai trouvé qu'une qui fonctionne, mais c'est encombrant.

Supposons la structure suivante dans mymodule.py

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

J'ai essayé les options suivantes pour <link to foo>:

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

Le seul qui produit effectivement un lien est: func: `mymodule.MyClass.foo`, mais le lien est affiché comme mymodule.MyClass.foo()et je veux un lien qui est affiché comme foo()ou foo.
Aucune des options ci-dessus ne produit de lien dans Spyder.

Merci de votre aide.


Que signifie "ajouter ... de l'intérieur" ??? Quelle est la différence entre un lien et un hyperlien?
eyquem

J'ai remplacé hyperlinkpar linkpour éviter toute confusion.
saroele

Je ne comprends toujours pas très bien votre question. Voulez-vous dire que vous voulez effectuer, à partir de Sphinx ou de Spyder ou d'autres IDE Python, une interrogation de la docstring de la fonction barqui donnera l'information "la fonction ou la méthode que vous recherchez est foo" ?
eyquem

Deuxièmement, quelle différence faites-vous entre mymodule.MyClass.foo()et foo()? Et qu'est-ce que vous appelez «affichage» ? Est-ce l'affichage d'une chaîne? Ou voulez-vous qu'un objet soit retourné? Dans ce dernier cas, les paens à la fin mymodule.MyClass.foo()et foo()sont trop.
eyquem

Désolé pour la confusion, il est toujours difficile d'expliquer une question de manière concise. Je veux juste avoir un lien sur lequel vous pouvez cliquer, qui vous mènera à la docstring de foo () (dans la fenêtre de documentation de l'EDI, ou dans la version html de Sphinx). Concernant les parenthèses: elles sont correctes:: func: a mymodule.MyClass.fooabouti au lien ayant les parenthèses. Et j'ai reformulé légèrement la question à nouveau.
saroele

Réponses:


88

La solution qui fonctionne pour Sphinx est de préfixer la référence avec ~.

Selon la documentation Sphinx sur la syntaxe des références croisées ,

Si vous préfixez le contenu avec ~, le texte du lien ne sera que le dernier composant de la cible. Par exemple ~Queue.Queue.get,: py: meth: fera référence à Queue.Queue.get mais n'affichera que get comme texte du lien.

La réponse est donc:

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

Il en résulte un html ressemblant à ceci:, This method does the same as foo()et foo()est un lien.

Cependant, notez que cela peut ne pas s'afficher dans Spyder sous forme de lien.


15
( Spyder dev ici ) @saroele Je prévois d'améliorer cette situation à l'avenir. Je suis tout à fait d'accord que ce serait vraiment cool de l'avoir;)
Carlos Cordoba

C'est vraiment génial, j'ai hâte d'y être. Merci pour tout votre travail sur Spyder!
saroele

Vous pouvez le faire avec le :any:rôle - voir la note sur default_setting.
naught101

1
est-il possible de faire des références croisées sans utiliser le chemin complet du module?
Jonathan le

2
Au lieu de :func:ça, j'ai trouvé que ça devait l'être :meth:.
Leo Fang

37

Si vous souhaitez spécifier manuellement le texte du lien, vous pouvez utiliser:

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

Pour plus d'informations, consultez la rubrique Références croisées d'objets Python .


Cela fonctionne, merci. En regardant le lien, j'ai découvert que préfixer la référence avec ~est plus proche de ce dont j'ai besoin. J'ai mis cela dans une réponse distincte. Cela ne fonctionne toujours pas dans Spyder cependant ...
saroele

-4

Il me semble que vous n'avez qu'à ajouter __name__ou __doc__à votre expression pour obtenir ce que vous voulez.
Je ne suis toujours pas sûr d'avoir bien compris l'objectif

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__

résultat

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

<function foo at 0x011C27B0>
foo
I am the docstring of foo

1
Je pense que vous avez manqué le point de la question: je veux avoir un lien (hyperlien) dans le html de ma documentation construite par Sphinx.
saroele

Vous avez raison, je rate le point. Et c'est parce que je ne connais pas Sphinx. alors j'ai essayé d'installer Sphinx. Mais je n'ai pas réussi. Je suis sous Windows et j'ai essayé d'utiliser sphinx-quickstart comme indiqué dans la doc. Mais je pense avoir une mauvaise compréhension du processus d’installation. Je ne peux pas t'aider, désolé. Je ne sais pas ce qui doit être compris par «hyperlien» dans le contexte de Sphinx.
eyquem
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.