swev-id: sphinx-doc__sphinx-9281 — Autodoc: configurable Enum default rendering in signatures [skip ci]

[casey-brooks]

Summary

• Add stringify_default_value helper and autodoc_enum_default_rendering config hook for enum defaults.
• Plumb enum rendering style through autodoc documenters and update documentation.
• Extend util and autodoc tests plus enum fixtures for configurable default coverage.

Resolves #74.

Reproduction steps

External minimal example:

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

Observed signature:

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

Expected signature:

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

Internal minimal example:

• Define:

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

def foo(x: MyEnum = MyEnum.ValueA):
    pass

• Use autodoc:

.. autofunction:: foo

• Default build shows <MyEnum.ValueA: 10>; with autodoc_enum_default_rendering = 'name', shows MyEnum.ValueA.

Environment info (local testing)

• Python: 3.9.5 and 3.11.8
• Sphinx: branch sphinx-doc__sphinx-9281
• Extensions: autodoc

Tests

• PYTHONPATH=/workspace/sphinx .venv/bin/pytest tests/test_ext_autodoc.py -k enum_default_rendering -q – 4 passed
• PYTHONPATH=/workspace/sphinx .venv/bin/pytest tests/test_util_inspect.py -k enum_defaults -q – 1 passed
• PYTHONPATH=/workspace/sphinx .venv/bin/flake8 sphinx/util/inspect.py sphinx/ext/autodoc/__init__.py tests/test_util_inspect.py tests/test_ext_autodoc.py – no lint errors
• PYTHONPATH=/workspace/sphinx .venv/bin/pytest – 1676 passed, 21 failed, 22 skipped (failures are long-standing: missing ImageMagick convert, BuildDoc source-dir option, and legacy typing/restify expectation drift)

CI and PR state

• PR marked as Draft.
• Commits include [skip ci] to avoid CI runs.

[casey-brooks]

Test & Lint Summary

• PYTHONPATH=/workspace/sphinx .venv/bin/pytest tests/test_ext_autodoc.py -k enum_default_rendering -q
• PYTHONPATH=/workspace/sphinx .venv/bin/pytest tests/test_util_inspect.py -k enum_defaults -q
• PYTHONPATH=/workspace/sphinx .venv/bin/flake8 sphinx/util/inspect.py sphinx/ext/autodoc/init.py tests/test_util_inspect.py tests/test_ext_autodoc.py
• PYTHONPATH=/workspace/sphinx .venv/bin/pytest (fails: 21 pre-existing suite failures around missing convert, BuildDoc source-dir, and typing/restify/restify-type expectation drift)

[noa-lucent]

Thanks for the thorough update—docs and tests look great. I left one blocker: overloaded method signatures still go through the old repr path, because MethodDocumenter.format_signature() never propagates the new enum_default_rendering kwarg. Please mirror the other documenters by defaulting that kwarg in the method override and add regression coverage for an overloaded method. Once that's in place I'm happy to take another look.

[casey-brooks]

✅ Addressed the overload path so MethodDocumenter now forwards autodoc_enum_default_rendering, and added an Enum-based overload fixture plus test_overload_enum_default_rendering to lock it in.

Test & Lint Summary

• PYTHONPATH=/workspace/sphinx .venv/bin/pytest tests/test_ext_autodoc.py -k overload_enum_default_rendering -q
• PYTHONPATH=/workspace/sphinx .venv/bin/pytest tests/test_ext_autodoc.py -k enum_default_rendering -q
• PYTHONPATH=/workspace/sphinx .venv/bin/pytest tests/test_util_inspect.py -k enum_defaults -q
• PYTHONPATH=/workspace/sphinx .venv/bin/flake8 sphinx/ext/autodoc/init.py tests/roots/test-ext-autodoc/target/overload.py tests/test_ext_autodoc.py
• PYTHONPATH=/workspace/sphinx .venv/bin/pytest (not rerun here; still has the 21 known failures from missing ImageMagick convert, BuildDoc source-dir, and legacy typing/restify expectations)

[noa-lucent]

Verified the follow-up: MethodDocumenter.format_signature() now threads enum_default_rendering, and the new overloaded-method fixture plus autodoc test cover the regression path. Everything looks good — thanks for closing the gap.