Link do metody klasy w docstringu języka Python

87

Chcę dodać link do metody w mojej klasie z poziomu dokumentacji innej metody tej samej klasy. Chcę, aby link działał w sfinksie, a preferencyjnie również w Spyder i innych Python IDE.

Wypróbowałem kilka opcji i znalazłem tylko jedną, która działa, ale jest uciążliwa.

Załóżmy, że następująca struktura w mymodule.py

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

Wypróbowałem następujące opcje <link to foo>:

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

Jedynym, który skutecznie tworzy link, jest: func: `mymodule.MyClass.foo`, ale link jest wyświetlany jako mymodule.MyClass.foo()i chcę, aby był wyświetlany jako foo()lub foo.
Żadna z powyższych opcji nie tworzy linku w Spyder.

Dzięki za pomoc.

saroele
źródło
Co to znaczy „dodaj ... od wewnątrz” ??? Jaka jest różnica między łączem a hiperłączem?
eyquem
Zastąpiłem hyperlink, linkaby uniknąć nieporozumień.
saroele
Nadal nie rozumiem dobrze twojego pytania. Czy masz na myśli, że chcesz wykonać, ze Sphinx lub Spyder lub z innych Python IDE, przesłuchanie dokumentacji funkcji bar, która dostarczy informacji "funkcja lub metoda, której szukasz to foo" ?
eyquem
Po drugie, jaką różnicę robisz między mymodule.MyClass.foo()a foo()? A co nazywasz „wyświetlaczem” ? Czy to wyświetlanie ciągu? A może chcesz, aby obiekt został zwrócony? W tym ostatnim przypadku paeny na końcu mymodule.MyClass.foo()i foo()to za dużo.
eyquem
Przepraszamy za zamieszanie, zawsze trudno jest zwięźle wyjaśnić pytanie. Chcę tylko mieć link, który możesz kliknąć, który przeniesie Cię do docstringu foo () (w oknie dokumentacji IDE lub w kompilacji html Sphinx). Odnośnie nawiasów: są one poprawne:: func: mymodule.MyClass.foospowodowało, że link ma nawiasy. I ponownie nieco przeformułowałem pytanie.
saroele

Odpowiedzi:

88

Rozwiązaniem, które działa w przypadku Sphinx, jest poprzedzenie odwołania znakiem ~.

Zgodnie z dokumentacją Sphinx dotyczącą składni odsyłaczy ,

Jeśli przedrostek treści zostanie poprzedzony znakiem ~, tekst odsyłacza będzie tylko ostatnim składnikiem celu. Na przykład: py: meth: ~Queue.Queue.getbędzie odnosić się do Queue.Queue.get, ale jako tekst odsyłacza wyświetli get.

Tak więc odpowiedź brzmi:

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

Powoduje to, że kod HTML wygląda następująco: This method does the same as foo()i foo()jest linkiem.

Należy jednak pamiętać, że może to nie być wyświetlane w Spyder jako łącze.

saroele
źródło
15
( Spyder dev tutaj ) @saroele Planuję poprawić tę sytuację w przyszłości. Całkowicie się zgadzam, że byłoby naprawdę fajnie mieć to;)
Carlos Cordoba
To naprawdę świetne, nie mogę się doczekać. Dzięki za całą twoją pracę nad Spyder!
saroele
Możesz to zrobić z :any:rolą - zobacz notatkę o default_setting.
naught101
1
czy możliwe jest odsyłanie bez użycia pełnej ścieżki modułu?
Jonathan
2
Zamiast tego :func:stwierdziłem, że tak musi być :meth:.
Leo Fang
37

Jeśli chcesz ręcznie określić tekst linku, możesz użyć:

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

Aby uzyskać więcej informacji, sprawdź odsyłacze do obiektów języka Python .

devin_s
źródło
To działa, dzięki. Patrząc na link, odkryłem, że prefiks odwołania do ~jest bliższy temu, czego potrzebuję. Umieściłem to w osobnej odpowiedzi. Jednak nadal nie działa w Spyder ...
saroele
-4

Wydaje mi się, że wystarczy dodać __name__lub __doc__do wyrażenia, aby uzyskać to, czego chcesz.
Nadal nie jestem pewien, czy poprawnie zrozumiałem cel

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__

wynik

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

<function foo at 0x011C27B0>
foo
I am the docstring of foo
eyquem
źródło
1
Myślę, że przegapiłeś sedno pytania: chcę mieć link (hiperłącze) w html mojej dokumentacji zbudowanej przez Sphinx.
saroele
Masz rację, nie rozumiem. A to dlatego, że nie znam Sfinksa. więc próbowałem zainstalować Sphinx. Ale mi się nie udało. Jestem w systemie Windows i próbowałem użyć sphinx-quickstart, jak wspomniano w dokumencie. Ale myślę, że źle zrozumiałem proces instalacji. Nie mogę ci pomóc, przepraszam. Nie wiem, co musi oznaczać „hiperłącze” w kontekście Sfinksa.
eyquem