Sphinx:ivar标签寻找交叉引用

Question

我想用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

会导致此错误:

mylibrary.module1.A的module1.py:docstring:无:警告:找到多个目标为交叉引用u'x':mylibrary.module1.Cx,mylibrary.module1.Bx

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

Answer 1

这是一个禁用ivar交叉引用的猴子补丁(基于Sphinx 1.5.1).我不确定最佳解决方案是什么,所以请考虑补丁是一个实验性的建议.要试用它,请将以下代码添加到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 2

正如mzjn提到的，这篇 SO 帖子有一个悬而未决的问题。在该线程中也已经发布了针对该问题的解决方法。总之，您使用内联注释#:而不是文档字符串。

在此处查看python.py用户引用的提交中的文件。文档字符串条目被删除（红线），并且他在构造函数中添加了内联注释（绿线）。

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

(...)
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:. 没有类型支持，并且它始终呈现默认值。