Python Enum values (used to show default values in function signatures) are rendered ugly.

[sidneycadot]

Python Enum values (used to show default values in function signatures) are rendered ugly.

To Reproduce

I made a minimal example to show the issue:

https://github.com/sidneycadot/sphinx_issue_ugly_enum

$ git clone git@github.com:sidneycadot/sphinx_issue_ugly_enum.git
$ cd sphinx_issue_ugly_enum/
$ make html
$ firefox build/html/index.html 

Expected behavior

I would hope the signature rendered as:

ugly_enum_func(e: ugly_enum.MyEnum = MyEnum.ValueA) → None

Unfortunately, it renders as:

ugly_enum_func(e: ugly_enum.MyEnum = <MyEnum.ValueA: 10>) → None

Environment info

• Python version: 3.9.5
• Sphinx version: 4.0.2
• Sphinx extensions: autodoc

[sidneycadot]

Probably the repr() representation of default arguments is used, and it should be; that is supposed to give a string that, when evaluated, yields the value.

Unfortunately, the enum.Enum implementation in Python does not honor this convention; their repr() includes the Enum value and the "<>" brackets.

In an ideal world we could ask the enum.Enum people to fix that behavior; but I am afraid that would break quite a lot of code in the wild.

The best course of action may be to special-case Enum types in autodoc.

[sidneycadot]

Searched the Python bug-tracker. There is some active discussion going on there to see if/how they should change repr for Enum classes:

https://bugs.python.org/issue40066

[sidneycadot]

A workaround for the issue is to provide a __repr__ emplementation with Enum types, which may be a good idea anyway until the Python folks sort this out:

class MyEnum(enum.Enum):
    ValueA = 10
    ValueB = 20

    def __repr__(self):
        return "MyEnum." + self.name

[tk0miya]

+1 Reasonable.