http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects的Sphinx文档说,
:py:func:引用Python函数;可以使用点名。角色文本不需要包括尾随括号以增强可读性;如果add_function_parentheses配置值为True(默认值),它们将由Sphinx自动添加。
:py:meth:引用对象的方法。角色文本可以包括类型名称和方法名称;如果它出现在类型的描述中,则可以省略类型名称。可以使用点状名称。
但我发现他们的行为方式没有任何区别。
这是我生成文档的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
包含创建它的角色的名称。例如,code
角色的:func:
元素将如下所示:
<code class="xref py py-func docutils literal">
而对于:meth:
角色,它将有py-meth
而不是py-func
。 Sphinx附带的库存CSS样式不区分py-meth
和py-func
,但是可以使用样式表来对它们进行不同的样式。
对于踢,我尝试过其他角色(例如class
)并让它们指向对象上的方法。即使没有任何意义,狮身人面像也没有任何问题。
它是在生成的索引中使用的语义信息,例如将某事物标记为函数或方法。正如路易斯已经提到的,可以通过CSS在HTML中对它们进行不同的样式设置。
在功能方面至少存在一个差异。
每当您使用autoclass语法(类名前面的.
)时,要自动解析完整的类名:
:meth:`.myClass`
将搜索范围限制为当前模块。:func:`.myClass`
也解决了外部课程。