Sphinx 文档中的人类可读迭代

Question

Sphinx-autodoc 扁平化了字典、列表和元组 - 使长的几乎不可读。漂亮的印刷格式也不总是需要的，因为一些嵌套容器最好保持扁平而不是圆柱形。有没有办法在源代码中显示可迭代对象 as typed？

Answer 1

直接从源代码获取，并为其添加 .rst 命令：

# conf.py
from importlib import import_module
from docutils  import nodes
from sphinx    import addnodes
from inspect   import getsource
from docutils.parsers.rst import Directive

class PrettyPrintIterable(Directive):
    required_arguments = 1

    def run(self):
        def _get_iter_source(src, varname):
            # 1. identifies target iterable by variable name, (cannot be spaced)
            # 2. determines iter source code start & end by tracking brackets
            # 3. returns source code between found start & end
            start = end = None
            open_brackets = closed_brackets = 0
            for i, line in enumerate(src):
                if line.startswith(varname):
                    if start is None:
                        start = i
                if start is not None:
                    open_brackets   += sum(line.count(b) for b in "([{")
                    closed_brackets += sum(line.count(b) for b in ")]}")

                if open_brackets > 0 and (open_brackets - closed_brackets == 0):
                    end = i + 1
                    break
            return '\n'.join(src[start:end])

        module_path, member_name = self.arguments[0].rsplit('.', 1)
        src = getsource(import_module(module_path)).split('\n')
        code = _get_iter_source(src, member_name)

        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', PrettyPrintIterable)

示例 .rst 和结果：

(:autodata:带空:annotation:是为了排除原来扁平化的字典)

部分代码借鉴自。

Sphinx 文档中的人类可读迭代

Human readable iterables in Sphinx documentation

restructuredtext

python-sphinx

autodoc