使用 Sphinx Autodoc 的漂亮打印特殊方法

Question

在Python documentation中，特殊方法的记录不同。例如，文档中显示的不是 __len__，而是 len(d)。我怎样才能让 Sphinx 做同样的事情？

似乎我所要做的就是覆盖生成方法名称的逻辑，但我不确定该怎么做。现有的 autodocs 事件似乎不允许这样做。

Answer 1

此答案已过时。源自此代码的 prettyspecialmethods 扩展提供了更好、更完整的功能。

正如 DeepSpace 所指出的，这不是内置功能； Python 文档手动执行此操作。

相反，我写了一个 Sphinx 转换：

from sphinx.transforms import SphinxTransform
import sphinx.addnodes as SphinxNodes

SPECIAL_METHODS = {
    '__getitem__': '{self}[{0}]',
    '__setitem__': '{self}[{0}] = {1}',
    '__delitem__': 'del {self}[{0}]',
    '__contains__': '{0} in {self}',

    '__lt__': '{self} < {0}',
    '__le__': '{self} <= {0}',
    '__eq__': '{self} == {0}',
    '__ne__': '{self} != {0}',
    '__gt__': '{self} > {0}',
    '__ge__': '{self} >= {0}',

    '__hash__': 'hash({self})',
    '__len__': 'len({self})',

    '__add__': '{self} + {0}',
    '__sub__': '{self} - {0}',
    '__mul__': '{self} * {0}',
    '__matmul__': '{self} @ {0}',
    '__truediv__': '{self} / {0}',
    '__floordiv__': '{self} // {0}',
    '__mod__': '{self} % {0}',
    '__divmod__': 'divmod({self}, {0})',
    '__pow__': '{self} ** {0}',
    '__lshift__': '{self} << {0}',
    '__rshift__': '{self} >> {0}',
    '__and__': '{self} & {0}',
    '__xor__': '{self} ^ {0}',
    '__or__': '{self} | {0}',

    '__neg__': '-{self}',
    '__pos__': '+{self}',
    '__abs__': 'abs({self})',
    '__invert__': '~{self}',
}

class PrettifySpecialMethods(SphinxTransform):
    default_priority = 800

    def apply(self):
        methods = (
            sig for sig in self.document.traverse(SphinxNodes.desc_signature)
            if 'class' in sig
        )

        for ref in methods:
            name_node = ref.next_node(SphinxNodes.desc_name)
            method_name = name_node.astext()

            if method_name in SPECIAL_METHODS:
                param_names = [ p.astext() for p in ref.traverse(SphinxNodes.desc_parameter) ]

                ref.remove(ref.next_node(SphinxNodes.desc_parameterlist))

                name_node.replace_self(
                    SphinxNodes.desc_name(
                        name_node.source,
                        SPECIAL_METHODS[method_name].format(*param_names, self='d'),
                        **name_node.attributes
                    )
                )

我还没有彻底测试它，它缺少一些功能，但这应该是一个开始（希望对某人有所帮助）。

Answer 2

使用 sphinxcontrib.prettyspecialmethods，正是这样做的。

使用 Sphinx Autodoc 的漂亮打印特殊方法

Pretty-print special methods using Sphinx Autodoc

python

python-sphinx

autodoc