位于 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 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.
但我无法发现它们的行为方式有任何差异。
这是我为其生成文档的 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:
角色的区别是什么?您能否举例说明它们的行为不同?
最佳答案
我看过 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 也没有问题。
关于python - :func: and :meth: roles in Python Sphinx? 之间的行为有什么区别,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/34848253/