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 toQueue.Queue.getbut only displaygetas 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.
Answer from saroele on Stack OverflowThe 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 toQueue.Queue.getbut only displaygetas 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.
If you want to manually specify the text of the link you can use:
:func:`my text <mymodule.MyClass.foo>`
For more information, checkout Cross-referencing Python objects.
Is this docstring correct ? should 'Args' or 'Parameters', can I avoid have empty line with special character?
What is the "working" Python docstring style for VS Code tooltips?
How do you guys refer to variables in your comments?
Python look up functions/class documentation in Atom?
I think you want a little description of what the function does when you are typing.
If that's what you want, there is autocomplete-python.
More on reddit.comDifferent tools access docstrings differently. For example, having a common base class that provides this docstring may be sufficient for some tools but not others.
The most general approach would be to define a functools.wraps() like decorator that copies the docstring of a function, e.g.:
def is_documented_by(original):
def wrapper(target):
target.__doc__ = original.__doc__
return target
return wrapper
class Waldo:
@is_documented_by(Foo.getBar)
def getBar():
...
But since this requires executing the Python code, static analyzers like Pylint may not like this. The best solution depends on the tools you are going to use.
The approach I've implemented for this was the following:
class Field_Sampler:
def getBar(self,pos):
"""
This is the Bar method.
It calculates and returns the Bar field effect generated
by this source based on `pos`
"""
import warnings
warnings.warn(
"called getBar method is not implemented in this class,"
"returning 0", RuntimeWarning)
return 0
class Foo(Field_Sampler):
"""This is the Foo class Docstring. It is a type of Bar source."""
def getBar(self,pos):
effect = pos + 1
return effect
class Waldo(Field_Sampler):
"""This is the Waldo class Docstring. It's also a type of Bar source."""
def getBar(self,pos):
effect = pos + 2
return effect
class Epsilon(Field_Sampler):
"""[WIP]This is the Epsilon class Docstring. It's also a type of Bar source."""
pass
A top class has the function prototype with the docstring. Classes inherit this and override the implementation definition of the method. If there's no docstring on the overriden function, then the docstring of the parent is used by most doc interpreters, including Sphinx.
This allowed me to set up the numerous classes while retaining the structure (which included more methods) and stopping static analyzers from freaking out. In the event the method wasn't implemented yet, we have it throw a warning if someone happens to call it.