狮身人面像：ivar标签去寻找交叉引用

Question

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

:ivar varname: description 
:ivar type varname: description 

但是我看到一个奇怪的现象，那就是狮身人面像搜索我的项目为变量名，并试图创建符号链接。 例如验证码：

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 

将导致此错误：

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

我才明白正确的目的或用途：伊娃？

Answer 1

由于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 
    (...) 

正如尼克·巴斯汀该注意变通呈现从:ivar:完全不同。没有类型支持，并且它总是呈现默认值。

Answer 2

这是一个猴子补丁（基于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。

Answer 3

有其他优点的替代方案。只需在类作用域中定义成员变量并使用纯文档字符串将其文档化即可。稍后，您可以使用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。