The Sphinx documentation at http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects says,
:py:func: Reference a Python function; dotted names may be used. The role text needs not include trailing parentheses to enhance readability; they will be added automatically by Sphinx if the add_function_parentheses config value is True (the default).
:py:meth: Reference a method of an object. The role text can include the type name and the method name; if it occurs within the description of a type, the type name can be omitted. A dotted name may be used.
But I could not find any difference in the way they behave.
Here is my Python module for which I generated documentation.
"""foo module."""
def hello(name):
"""Print hello addressed to *name*.
Args:
name (str): Name to address.
"""
print('hello', name)
class Foo:
"""Foo class."""
def bye(self, name):
"""Print bye addressed to *name*.
Args:
name (str): Name to address.
"""
print('bye', name)
if __name__ == '__main__':
hello('world')
Foo().bye('python')
This is what I have in my index.rst file.
Foo Documentation
=================
See :func:`foo.hello` and :func:`foo.Foo.bye`.
Also, see :meth:`foo.hello` and :meth:`foo.Foo.bye`.
foo module
==========
.. automodule:: foo
:members:
After performing a make html, this is the output I see.
Both :func: and :meth: roles have generated valid cross-referencing hyperlinks to hello and Foo.bye regardless of whether the target is a function or a method.
What then is the difference between :func: and :meth: roles. Can you provide an example for which they behave differently?
