CODEWITHSUNDEEP
pythonpython-sphinxautodoc
Thom Smith
Thom Smith

Reputation: 14086

Pretty-print special methods using Sphinx Autodoc

In the Python documentation, special methods are documented differently. For instance, instead of __len__, the documentation reads len(d). How can I get Sphinx to do the same?

It seems like all I have to do is override the logic producing the method name, but I'm not sure how to do that. The existing autodocs events don't seem to allow it.

Upvotes: 0

Views: 280

Answers (2)

Thom Smith
Thom Smith

Reputation: 14086

This answer is obsolete. The prettyspecialmethods extension, which is descended from this code, provides much better and more complete functionality.

As DeepSpace points out, this isn't built-in functionality; the Python docs do this manually.

Instead, I wrote a Sphinx transform:

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
                    )
                )

I haven't thoroughly tested this, and it's missing some features, but it should be a start (and hopefully helpful to someone).

Upvotes: 1

Thom Smith
Thom Smith

Reputation: 14086

Use sphinxcontrib.prettyspecialmethods, which does exactly this.

Upvotes: 0

Related Questions