狮身人面像：依瓦尔·塔格寻找交叉引用 [英] Sphinx :ivar tag goes looking for cross-references

问题描述

我想用Sphinx来记录Python对象属性。我知道我应该使用

:ivar varname: description
:ivar type varname: description

但是，我看到了一种奇怪的行为，即Sphinx在我的项目中搜索变量名并尝试创建符号链接。 例如，代码如下：

class A(object):
    """
    :ivar x: some description
    """
    def __init__(self, x):
        self.x = x

class B(object):
    def x(self):
        return 1

class C(object):
    def x(self):
        return 2

将导致此错误：

mode1.py：myLibrary.mode1.A：无：警告：找到多个交叉引用的目标u‘x’：myLibrary.mode1.C.x，myLibrary.mode1.B.x

我是不是理解错了：ivar的用途或用法？

推荐答案

这里有一个猴子补丁(基于Sphinx 1.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。

这篇关于狮身人面像：依瓦尔·塔格寻找交叉引用的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！