在Sphinx文档中展示字典数据

Question

我有一个Python项目源代码中的字典，用于描述默认配置值。这个字典非常长。我希望在Sphinx文档中以除“查看源代码”之外的其他格式查看字典，以便人们可以快速检查默认值。

使用Sphinx autodoc时，Sphinx是否提供格式化类似字典的变量为人类可读格式的选项？目前我正在使用..automodule::来转储整个模块，我在文档中得到字典作为一个长字符串转储（没有换行符、漂亮打印等），基本上是不可读的。

• Sphinx是否提供工具来打印单独源代码变量的值？

• 是否有任何漂亮的打印可用？

- Mikko Ohtamaa

Answer 1

这可能不是最优雅的解决方案（编写一个适当的指令以输出漂亮格式的字典会更好），但现在它可以工作：

在Sphinx .conf文件中添加自定义exec指令，如此处所示，然后在您想要打印字典的.rst文件中，做如下操作：

.. exec::
    import json
    from some_module import some_dictionary
    json_obj = json.dumps(some_dictionary, sort_keys=True, indent=4)
    print '.. code-block:: JavaScript\n\n    %s\n\n' % json_obj

这将在您的文档中以JavaScript代码块的形式打印出字典（我认为这是呈现字典的最佳方式）。

- Erve1879

---

我的最后一个 { 括号字符渲染出了代码块。有什么想法可以修复这个问题吗？ - jsmedmar

你可能想要在代码块中加入 json_obj = json_obj[:-1] + " }" 以渲染最后一个 { 字符。 - jsmedmar

你可以使用pprint标准库模块来直接漂亮地打印本地数据结构，而不是将其序列化和反序列化为JSON。 - Freso

Answer 2

如果字典值未被计算且不像这样易于人类阅读：

FRUITS = {
   "Apple": "Red and Delicious",
   # note: eating too much orange make your hands orange
   "Orange": "A lot of vitamin C"
}

假设你在fruit.py文件的第15行开始定义了上述字典。

那么你可以这样做:

.. literalinclude:: ../path-to-file/fruit.py
   :language: python
   :lines: 15-
   :linenos:

您将在文档中看到易于阅读的值以及相关注释等内容

- naoko

Answer 3

我需要回答这个问题，但不喜欢现有的答案，所以我花了一些时间思考并得出了一个不完美但可接受的解决方案。

它使用pprint.pformat生成节点，但我不能想出如何生成包括交叉引用目标在内的全部标记，因为如果我尝试添加外层，它会报错KeyError: 'objtype' ，Sphinx文档没有任何帮助，相关的Sphinx扩展程序也非常复杂。

from importlib import import_module
from pprint import pformat
from docutils.parsers.rst import Directive
from docutils import nodes
from sphinx import addnodes

class PrettyPrintDirective(Directive):
    """Render a constant using pprint.pformat and insert into the document"""
    required_arguments = 1

    def run(self):
        module_path, member_name = self.arguments[0].rsplit('.', 1)

        member_data = getattr(import_module(module_path), member_name)
        code = pformat(member_data, 2, width=68)

        literal = nodes.literal_block(code, code)
        literal['language'] = 'python'

        return [
                addnodes.desc_name(text=member_name),
                addnodes.desc_content('', literal)
        ]


def setup(app):
    app.add_directive('pprint', PrettyPrintDirective)

这是我如何使用它的方式：

.. automodule:: quicktile.__main__
   :members:
   :exclude-members: XDG_CONFIG_DIR,DEFAULTS,CfgDict

----

.. pprint:: quicktile.__main__.DEFAULTS

(DEFAULTS 是一个字典，用于在找不到配置文件时创建带有默认值的配置文件。)

...这是它的样子：

- ssokolow

---

好的方法；我基于此制作了一个变体，可以保留源代码格式，在这里。 - OverLordGoldDragon

Answer 4

大家好，我已经完成了它，但你们可能不会相信我，因为它只有五行代码和导入语句。在回复中对我进行嘲笑吧，但这段代码已经运行了一两周，我还没有发现它出现任何问题。

以下是在conf.py文件中的代码：

from pprint import pformat
def object_description(object) -> str:
    return pformat(object, indent=4)

from sphinx.util import inspect
inspect.object_description = object_description

这需要一些时间~哎呦~

变成一个 ~嗯嗯~ 的：

编辑：修复了图片，因为我得到了足够的 ~声望~ 来拥有它们。

- sneakers-the-rat

Answer 5

基于 Erve1879的帖子，进一步开发。

此解决方案没有尾随括号。

将此处给出的自定义exec指令添加到您的Sphinx .conf文件中，然后在您想要打印字典的.rst文件中，像下面RST部分所示那样进行操作。

textwrap.indent被用来缩进所需的字典内容。

data = pad + 'STYLE_PARTS = ' + data.lstrip()此行从数据开头删除填充。请参见下面OUTPUT的第一行。

另请参阅：

使用textwrap

RST

config
======

.. automodule:: config
    :members:
    :exclude-members: STYLE_PARTS

    .. exec::

        import json
        import textwrap
        from config import STYLE_PARTS
        pad = '    '
        cb = '.. code-block:: python\n\n'
        data = json.dumps(STYLE_PARTS, sort_keys=True, indent=4)
        data = textwrap.indent(text=data, prefix=pad)
        data = pad + 'STYLE_PARTS = ' + data.lstrip()
        cb = cb + data
        print(cb)

输出

STYLE_PARTS = {
    "0": "00",
    "1": "01",
    "2": "02",
    "3": "03",
    "4": "04",
    "5": "05",
    "6": "06",
    "7": "07",
    "8": "08",
    "9": "09",
    "bold": "BOLD",
    "continuance": "CONTINUANCE",
    "contract": "CONTRACT"
}

- Amour Spirit