獅身人面像：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。