Workaround for documenting Enum __new__ methods

[ipilcher]

Python enums (enum.Enum and its subclasses) have an annoying behavior. When creating an enum type, the EnumType metaclass replaces the orginal __new__ method, and it doesn't copy the docstring from the original __new__ to the replacement. This obviously prevents Sphinx autodoc from finding it.

Dropping the code snippet below into conf.py fixes this. It retrieves the orginal docstring from the enum type's _new_member_ attribute (which is the original __new__ method) and replaces the automatically retrieved docstring (usually None) with the original one.

The only part that isn't straightforward is tracking down the enum type's actual class object. Sphinx doesn't pass this in, and it isn't directly available from the method object. We have to parse the methods fully-qualified name and figure out where the module name ends and the class name begins (which isn't obvious in the case of a nested class). Thus, we start with the longest possible module name and shorten it one element at a time until we find a name that actually represents a module. From there, we start at the module namespace and recurse through the components of the class name (enclosing classes) until we arrive at the actual enum type class.

# SPDX-License-Identifier: CC0-1.0

import enum
import inspect
import sys

def fix_enum_new(app, what, name, obj, options, lines):
    if what != 'method':
        return
    try:
        if obj.__name__ != '__new__' or obj.__module__ != 'enum':
            return
        parts = name.split('.')[:-1]  # trim off __new__ at end
        if len(parts) < 2:
            return
        module_parts = parts[:-1]
        while module_parts:
            module_name = '.'.join(module_parts)
            if module_name in sys.modules:
                class_parts = parts[len(module_parts):]
                break
            module_parts.pop()
        else:
            return
        ns = sys.modules[module_name]
        for part in class_parts:
            ns = getattr(ns, part)
        if isinstance(ns, type) and issubclass(ns, enum.Enum):
            # This may raise an AttributeError, so do it before clearing lines
            doc = inspect.cleandoc(ns._new_member_.__doc__).split('\n')
            lines.clear()
            lines.extend(doc)
    except AttributeError:
        return

def setup(app):
    app.connect('autodoc-process-docstring', fix_enum_new)

[electric-coder]

I already use too many Enum workarounds that for this use case I'd simply copy-paste anything necessary verbatin into the rst declaration to at least have explicit control and simplify the problem. But knowing there's a dynamic fix is interesting.