What's the difference in behaviour between :func: and :meth: roles in Python Sphinx?

Question

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?

Answer 1

I've looked at Sphinx code. The only difference I was able to discern is that each of the roles generate HTML elements whose HTML class includes the name of the role that created it. For instance, the code element for a :func: role will look like this:

<code class="xref py py-func docutils literal">

Whereas for a :meth: role, it would have py-meth instead of py-func. The stock CSS style included with Sphinx does not distinguish between py-meth and py-func but it would be possible to have a stylesheet that styles them differently.

For kicks I've tried other roles (e.g. class) and had them point to methods on objects. Sphinx had no problem with it even if it made no sense.

Answer 2

There is at least one difference, in terms of functionality.

Whenever you use the autoclass syntax (. in front of the class name), to automatically resolve the full class name:

• :meth:`.myClass` limits the search scope to the current module.
• :func:`.myClass` also resolves external classes.

Answer 3

It is semantic information that is used in the generated index for instance to label something as function or method. As Louis already mentioned it would be possible to style them differently in HTML via CSS.