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.C.x，mylibrary.module1.B.x

我是否错误地理解了：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

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

:ivar float bandwidth: blah

与此：

:ivar float ~.bandwidth: blah

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

Answer 3

如 mzjn 所述，有一个open issue for this SO post。在该主题中，已经发布了该问题的解决方法。总之，您使用内联注释#:而不是文档字符串。

查看用户here引用的提交中的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:完全不同。没有类型支持，它总是呈现默认值。

Answer 4

还有其他优势。只需在类范围内定义成员变量，并使用纯文档字符串对其进行记录。稍后您可以使用py:attr:角色引用它们。它更具可读性，自我记录（是的，我知道这是在python-sphinx，但无论如何）和内省友好的方法。

module.py

class A:

    x = None
    '''This way there's no issue. It is more readable and friendly
    for class member introspection.'''


    def __init__(self, x):
        self.x = x

class B:
    '''Something about :py:attr:`.A.x`'''

    def x(self):
        '''Method x of B'''
        return 1

的README.txt

****
Test
****

.. autoclass:: module.A
   :members:

.. autoclass:: module.B
   :members:

conf.py

extensions = ['sphinx.ext.autodoc']

source_suffix = '.txt'

master_doc = 'README'

project = 'Test'

pygments_style = 'sphinx'

html_theme = 'alabaster'

html_use_index       = False
html_show_sourcelink = False
html_show_copyright  = False

html_sidebars = {'**': ['localtoc.html']}

像PYTHONPATH=. sphinx-build . html一样构建。

Answer 5

这终于在 2021 年 4 月 12 日发布的 Sphinx 4.0.0.beta1 中得到修复。

包含它的 Sphinx 的下一个稳定版本将是 4.0 或 4.1。

（问题：#5977，修复它的 PR：#8638，4.0 beta 1 的变更日志条目：here）

Sphinx：ivar标签寻找交叉引用

5 个答案: