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.
If you're using sphinx to generate your documentation
"""
`here <url>`__
"""
in your docstrings should be parsed properly.
Just add the link as a string into the docstring, like so:
def foo():
"""Lorem ipsum for more info, see here: www.myfancydocu.com""
The doctring is just a string, so there is no Hyperlink. But anyone that wants to look at the website can just copy the link.
There are automatic documentation-builders that build a documentation out of your code and docstrings in e.g. html. Those can probably add hyperlinks to the documentation with a specific syntax, but that syntax then depends on which documentation-builder you use. If you only have your code, then just adding the url as a string is all you can do.
Different 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.
Interactively, you can display it with:
help(my_func)
Or from code you can retrieve it with (surround it with print(.) to get a formatted output):
my_func.__doc__
You can also use inspect.getdoc. It cleans up the __doc__ by normalizing tabs to spaces and left shifting the doc body to remove common leading spaces.