以下行为之间的区别是什么:func:和:meth:Python Sphinx中的角色?

问题描述 投票:9回答:3

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后,这是我看到的输出。

Screeshot of foo documentation

:func::meth:角色都生成了有效的交叉引用超链接到helloFoo.bye,无论目标是函数还是方法。

那么:func::meth:角色之间的区别是什么。你能提供一个他们表现不同的例子吗?

python python-sphinx
3个回答
12
投票

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

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

而对于:meth:角色,它将有py-meth而不是py-func。 Sphinx附带的库存CSS样式不区分py-methpy-func,但是可以使用样式表来对它们进行不同的样式。

对于踢,我尝试过其他角色(例如class)并让它们指向对象上的方法。即使没有任何意义,狮身人面像也没有任何问题。


1
投票

它是在生成的索引中使用的语义信息,例如将某事物标记为函数或方法。正如路易斯已经提到的,可以通过CSS在HTML中对它们进行不同的样式设置。


1
投票

在功能方面至少存在一个差异。

每当您使用autoclass语法(类名前面的.)时,要自动解析完整的类名:

  • :meth:`.myClass`将搜索范围限制为当前模块。
  • :func:`.myClass`也解决了外部课程。
© www.soinside.com 2019 - 2024. All rights reserved.