Question

我有以下模块：

"""
This is a test.
"""

class Test(dict):
    """ Should always appear empty in the docs. """
    def __repr__(self): return '{}'
    def __str__(self): return '{}'
    def __format__(self, *args): return '{}'

#: This is a dictionary that appears appears to be empty in the docs, but isn't
#: really. Enjoy!
test = Test()
test['a'] = 1
test['b'] = 2

我用以下文件记录模块

.. automodule:: test
   :members:

一切都可以编译。但是，当我查看test.test的文档时，会看到

test.test = {'a': 1, 'b': 2}

sphinx autodoc如何获取数据对象的表示形式，如何覆盖它？ Test类的重点是产生以下输出：

test.test = {}

Answer 1

在此Python文件https://github.com/sphinx-doc/sphinx/blob/master/sphinx/util/inspect.py的object_description函数中创建字典值。该函数提供了“ repr（）实现，该返回可安全地在reST上下文中使用的文本”。

可以通过将autodata指令与annotation选项一起使用来覆盖Sphinx创建的表示形式。

.. automodule:: test
   :members:
   :exclude-members: test

.. autodata:: test.test
   :annotation: = {}

Answer 2

基于@mzjn's comment，我想出了一个非常骇人的解决方案，该解决方案在我的具体情况下确实有效，但是我不建议其他任何人使用。

诀窍在object_description函数的以下几行中：

if isinstance(object, dict):
    try:
        sorted_keys = sorted(object)
    except Exception:
        pass # Cannot sort dict keys, fall back to generic repr
    ...

如果sorted失败，则描述默认为repr。使sorted失败的最简单方法是使我的课程Test不可迭代：

def __iter__(self):
    raise TypeError('no!')

尽管对于通用字典扩展而言，这是极不推荐的，但它对于我的Test类来说却可以正常工作，并且可以产生预期的结果。

修改Sphinx中的数据表示

2 个答案: