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.
From PEP 257:
The docstring for a class should summarize its behavior and list the public methods and instance variables. If the class is intended to be subclassed, and has an additional interface for subclasses, this interface should be listed separately (in the docstring). The class constructor should be documented in the docstring for its __init__ method. Individual methods should be documented by their own docstring.
If a class subclasses another class and its behavior is mostly inherited from that class, its docstring should mention this and summarize the differences. Use the verb "override" to indicate that a subclass method replaces a superclass method and does not call the superclass method; use the verb "extend" to indicate that a subclass method calls the superclass method (in addition to its own behavior).
So if you want to follow Python standards, use language indicating that the method is overriden in your subclass docstring.
Do I just keep the docstring in the base class?
If your derived class has nothing to add to the description, this seems like the right choice - Python 3.5 and onwards will walk the inheritance to find a docstring:
import inspect
class Base:
def method(self):
"""Do something"""
class Derived(Base):
def method(self):
pass
print(inspect.getdoc(Derived.method)) # prints "Do something"
Note that this does not work if Derived is defined in an interactive console, but that shouldn't matter.
Yes just drop the methods section from the class docstring. I've never ever seen something like that used.(It is used in few places in the standard library.) The class docstring needs to just describe the class and the docstring of individual methods then handle describing themselves.
Also the wording in the PEP to me means that the class docstring "should" list the public methods, but not describe them in any other way.(This is also how the above standard library example does it.) But as said, I would never even do that, since the code speaks for itself and that kind of listing is bound to get out-of-date.
Final note: I personally prefer to use the Google docstring style, because to me it's the clearest and cleanest.
example:
class Animal:
"""
A class used to represent an Animal
...
Attributes
----------
says_str : str
a formatted string to print out what the animal says
name : str
the name of the animal
sound : str
the sound that the animal makes
num_legs : int
the number of legs the animal has (default 4)
Methods
-------
says(sound=None)
Prints the animals name and what sound it makes
"""
says_str = "A {name} says {sound}"
def __init__(self, name, sound, num_legs=4):
"""
Parameters
----------
name : str
The name of the animal
sound : str
The sound the animal makes
num_legs : int, optional
The number of legs the animal (default is 4)
"""
self.name = name
self.sound = sound
self.num_legs = num_legs
def says(self, sound=None):
"""Prints what the animals name is and what sound it makes.
If the argument `sound` isn't passed in, the default Animal
sound is used.
Parameters
----------
sound : str, optional
The sound the animal makes (default is None)
Raises
------
NotImplementedError
If no sound is set for the animal or passed in as a
parameter.
"""
if self.sound is None and sound is None:
raise NotImplementedError("Silent Animals are not supported!")
out_sound = self.sound if sound is None else sound
print(self.says_str.format(name=self.name, sound=out_sound))
Yep, listing methods in the class docstring, then each method again documented, according to this standard. I reccomend using sphinx, though: https://www.sphinx-doc.org/en/master/contents.html