Question

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

与Sphinx autodoc一起使用时，Sphinx是否提供格式化字典变量格式的选项？我目前正在使用.. automodule::转储整个模块，我将字典作为文档中的一个长字符串转储（没有新行，漂亮的打印，任何东西），基本上是不可读的。

Sphinx是否提供打印单个源代码变量值的工具
有漂亮的印刷吗？

Answer 1

这可能不是最优雅的解决方案（编写适当的指令来输出漂亮的打印字典会好得多），但现在这样做了：

将给定here的自定义exec指令添加到您的Sphinx .conf文件中，然后在.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代码块中打印出您的字典（我发现这是在文档中呈现字典的最佳方式）。

Answer 2

如果没有计算字典值并且像这样人类可读

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

说你从第15行开始在fruit.py中定义了上面的dict

然后你可以这样做：

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

您将在doc

上找到人类可读的值+评论等

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是用于创建没有默认值的配置文件的字典。）

...外观如下：

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

这需要你〜uh哦〜

image of sphinx docs without pretty formatting

变成〜uhhuh〜

image of sphinx docs with pretty formatting

编辑：固定图像b / c的〜rep〜足以容纳它们

在Sphinx文档中显示字典数据

4 个答案: