Link to class method in python docstring

saroele picture saroele · Jan 22, 2014 · Viewed 43.4k times · Source

I want to add a link to a method in my class from within the docstring of another method of the same class. I want the link to work in sphinx and preferentially also in Spyder and other Python IDE's.

I tried several options and found only one that works, but it's cumbersome.

Suppose the following structure 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'

I tried the following options for <link to foo>:

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

The only one that effectively produces a link is :func:`mymodule.MyClass.foo`, but the link is shown as mymodule.MyClass.foo() and I want a link that is shown as foo() or foo.
None of the options above produces a link in Spyder.

Thanks for your help.

Answer

saroele picture saroele · Jan 23, 2014

The solution that works for Sphinx is to prefix the reference with ~.

Per the Sphinx documentation on Cross-referencing Syntax,

If you prefix the content with ~, the link text will only be the last component of the target. For example, :py:meth:~Queue.Queue.get will refer to Queue.Queue.get but only display get as the link text.

So the answer is:

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

This results in an html looking like this : This method does the same as foo(), and foo() is a link.

However, note that this may not display in Spyder as a link.