斯芬克斯：ivar标签寻找交叉引用

Question

我想用Sphinx来记录Python对象属性。我明白我应该用

:ivar varname: description
:ivar type varname: description

但是我看到了一个奇怪的行为，即Sphinx在我的项目中搜索变量名并尝试创建符号链接。 E、 g.本代码：

^{pr2}$

将导致此错误：

module1.py:docstring of mylibrary.module1.A:None: WARNING: more than one target found for cross-reference u'x': mylibrary.module1.C.x, mylibrary.module1.B.x

我是否错误地理解了：ivar的目的或用法？在

Answer 1

以下是github上的@acrisci提供的一个解决方法：在变量名前面加上~.。例如替换

:ivar float bandwidth: blah

有了这个：

^{pr2}$

来源：https://github.com/sphinx-doc/sphinx/issues/2549#issuecomment-488896939

Answer 2

这是一个monkey补丁（基于sphinx1.5.1），它禁用ivar交叉引用。我不确定什么是最好的解决方案，所以把补丁看作是一个实验性的建议。要试用它，请将下面的代码添加到conf.py。在

from docutils import nodes
from sphinx.util.docfields import TypedField
from sphinx import addnodes

def patched_make_field(self, types, domain, items):
    # type: (List, unicode, Tuple) -> nodes.field
    def handle_item(fieldarg, content):
        par = nodes.paragraph()
        par += addnodes.literal_strong('', fieldarg)  # Patch: this line added
        #par.extend(self.make_xrefs(self.rolename, domain, fieldarg,
        #                           addnodes.literal_strong))
        if fieldarg in types:
            par += nodes.Text(' (')
            # NOTE: using .pop() here to prevent a single type node to be
            # inserted twice into the doctree, which leads to
            # inconsistencies later when references are resolved
            fieldtype = types.pop(fieldarg)
            if len(fieldtype) == 1 and isinstance(fieldtype[0], nodes.Text):
                typename = u''.join(n.astext() for n in fieldtype)
                par.extend(self.make_xrefs(self.typerolename, domain, typename,
                                           addnodes.literal_emphasis))
            else:
                par += fieldtype
            par += nodes.Text(')')
        par += nodes.Text(' -- ')
        par += content
        return par

    fieldname = nodes.field_name('', self.label)
    if len(items) == 1 and self.can_collapse:
        fieldarg, content = items[0]
        bodynode = handle_item(fieldarg, content)
    else:
        bodynode = self.list_type()
        for fieldarg, content in items:
            bodynode += nodes.list_item('', handle_item(fieldarg, content))
    fieldbody = nodes.field_body('', bodynode)
    return nodes.field('', fieldname, fieldbody)

TypedField.make_field = patched_make_field

原始的TypedField.make_field方法在这里：https://github.com/sphinx-doc/sphinx/blob/master/sphinx/util/docfields.py。在

Answer 3

正如mzjn所指，有一个open issue for this SO post。在这个线程中，也已经有了一个解决问题的方法。总之，您使用内联注释#:，而不是docstring。在

查看用户here引用的提交中的python.py文件。docstring条目被删除（红线），他在构造函数中添加了内联注释（绿线）。在

我一直在寻找这方面的文件，但找不到。 例如：

(...)
def __init__(self, function, fixtureinfo, config, cls=None, module=None):
    #: access to the :class:`_pytest.config.Config` object for the test session
    self.config = config
    (...)

正如Nick Bastin所指出的那样，这种处理方法的渲染方式与:ivar:完全不同。不支持类型，它总是呈现默认值。在