sphinx-doc
"inherited-members": "str" does not hide the inherited members in an Enum
Describe the bug
When an enum class also inheriting from string is documented with autodoc, the methods inherited from str are also included in the documentation.
How to Reproduce
With
.. autosummary::
:toctree: generated/api
TmpEnum
class TmpEnum(str, Enum):
"""
a test string enum according to https://docs.python.org/3/library/enum.html#notes
"""
FOO = "foo"
"""the foo value"""
BAR = "bar"
"""the bar value"""
with conf.py
autodoc_default_options = {
"members": True,
"inherited-members": "str",
"show-inheritance": True,
}
still shows the str methods:
It is the same when the StrEnum class is used instead even with "inherited-members": "str,StrEnum"
class TmpEnum(StrEnum):
"""
a test string enum using StrEnum
"""
FOO = "foo"
"""the foo value"""
BAR = "bar"
"""the bar value"""
Environment Information
Platform: win32; (Windows-10-10.0.22631-SP0)
Python version: 3.11.4 (tags/v3.11.4:d2340ef, Jun 7 2023, 05:45:37) [MSC v.1934 64 bit (AMD64)])
Python implementation: CPython
Sphinx version: 7.4.7
Docutils version: 0.20.1
Jinja2 version: 3.1.6
Pygments version: 2.19.1
Sphinx extensions
"sphinx.ext.autodoc" "sphinx.ext.autosummary"
Additional context
No response
current workaround is to use enum-tools
but it is a bit sad to have to decorate all enum classes with @enum_tools.documentation.document_enum in order to show proper doc.
from string is documented with autodoc
.. autosummary::
The issue here is that you're using autosummary, with autdoc the proper way to solve this would be declaring the class and members in the .rst explicitly thereby inherited members wouldn't be a problem if you don't declare them. I'm saying this for users who might not want to use an extension and instead want to keep their project vanilla as can be...
As for the signature of the class itself it can be overridden and the inheritance list can be patched using autodoc-process-bases (another problem if you start inheriting from metaclasses).
Thanks @electric-coder . So you are confirming that there is no solution as of today, apart from manually listing the content of the doc for each enum. Unless maybe autodoc-process-bases could be used in a generic way to patch all the enum classes found by autosummary ?
@smarie the last time I solved this was 2 years ago and I haven't rewritten my Enums since because they're working using the described solution. Your Sphinx version is 7.4.7 (somewhat old) and I vaguely recall someone in the repo complaining and maybe this issue has been fixed when inheriting from stdlib types. But I'm also not an autosummary user so I haven't tested it further.