What is the difference in behavior between: func: and: meth: roles in Python Sphinx?

Question

Sphinx documentation at http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects says

: py: func: Python function reference; dot names can be used. Role text should not include sliding parentheses to enhance readability; they will be added automatically by Sphinx if the add_function_parentheses configuration value is True (default).

: py: met: Link to the method of the object. Role text may include type name and method name; if this happens in the description of the type, the type name can be omitted. You can use a dotted name.

But I could not find a difference in how they behave.

Here is my Python module for which I generated the 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 the 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 doing make html this is the result I see.

Both roles :func: and :meth: generate valid hyperlink hyperlinks to hello and Foo.bye regardless of whether the target is a function or method.

What is the difference between the roles :func: and :meth: Can you give an example by which they behave differently?

Answer 1

I looked at the Sphinx code. The only difference that I could distinguish is that each of the roles generates HTML elements, the HTML class includes the name of the created role. For example, the code element for the role :func: would look like this:

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

Whereas for the role :meth: instead of py-func he would have py-meth . The CSS barcode included in Sphinx does not distinguish between py-meth and py-func , but one could have a stylesheet that styles them differently.

For hits I tried other roles (e.g. class ) and whether they pointed to methods on objects. The Sphinx did not have any problems with him, even if it did not make sense.

Answer 2

This is the semantic information that is used in the generated index, for example, to refer to something as a function or method. As Louis already mentioned, one could style them differently in HTML via CSS.