Question

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

似乎所有我要做的就是覆盖产生方法名称的逻辑，但我不知道该怎么做。现有的autodocs事件似乎不允许它。

Answer 1

正如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的漂亮打印特殊方法

2 个答案: