python - :func: and :meth: roles in Python Sphinx? 之间的行为有什么区别

Question

位于 http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects 的 Sphinx 文档说，

: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 theadd_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 ofa type, the type name can be omitted. A dotted name may be used.

但我无法发现它们的行为方式有任何差异。

这是我为其生成文档的 Python 模块。

"""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')

这是我的 index.rst 文件中的内容。

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:

执行 make html 后，这是我看到的输出。

:func: 和 :meth: 角色都生成了指向 hello 和 Foo.bye< 的有效交叉引用超链接 无论目标是函数还是方法。

那么 :func: 和 :meth: 角色的区别是什么？您能否举例说明它们的行为不同？

Answer 1

我看过 Sphinx 代码。我能够辨别的唯一区别是每个角色都会生成 HTML 元素，其 HTML class 包含创建它的角色的名称。例如，:func: 角色的 code 元素将如下所示:

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

而对于 :meth: 角色，它将具有 py-meth 而不是 py-func。 Sphinx 中包含的常用 CSS 样式不区分 py-meth 和 py-func，但可以有一个样式表来对它们进行不同的样式设置。

为了好玩，我尝试了其他角色(例如 class)并让它们指向对象上的方法。即使它毫无意义，Sphinx 也没有问题。