diff --git a/CHANGES b/CHANGES index eef72873f..31ddad9c5 100644 --- a/CHANGES +++ b/CHANGES @@ -9,6 +9,8 @@ Features added * #2513: A better default settings for XeLaTeX * #3096: ``'maxlistdepth'`` key to work around LaTeX list limitations +* #3060: autodoc supports documentation for attributes of Enum class. Now autodoc render + just the value of Enum attributes instead of Enum attribute representation. Bugs fixed ---------- diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 6a1d907fd..890f65646 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -31,7 +31,7 @@ from sphinx.application import ExtensionError from sphinx.util.nodes import nested_parse_with_titles from sphinx.util.compat import Directive from sphinx.util.inspect import getargspec, isdescriptor, safe_getmembers, \ - safe_getattr, object_description, is_builtin_class_method + safe_getattr, object_description, is_builtin_class_method, isenumattribute from sphinx.util.docstrings import prepare_docstring try: @@ -1478,6 +1478,8 @@ class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter): def import_object(self): ret = ClassLevelDocumenter.import_object(self) + if isenumattribute(self.object): + self.object = self.object.value if isdescriptor(self.object) and \ not isinstance(self.object, self.method_types): self._datadescriptor = True diff --git a/sphinx/util/inspect.py b/sphinx/util/inspect.py index 91c955e10..147d43592 100644 --- a/sphinx/util/inspect.py +++ b/sphinx/util/inspect.py @@ -94,6 +94,18 @@ else: # 2.7 pass return inspect.ArgSpec(args, varargs, varkw, func_defaults) +try: + import enum +except ImportError: + enum = None + + +def isenumattribute(x): + """Check if the object is attribute of enum.""" + if enum is None: + return False + return isinstance(x, enum.Enum) + def isdescriptor(x): """Check if the object is some kind of descriptor.""" diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index d290e050b..68e15bbed 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -14,6 +14,7 @@ from util import TestApp, Struct, raises, SkipTest # NOQA from nose.tools import with_setup, eq_ +import enum from six import StringIO from docutils.statemachine import ViewList @@ -825,6 +826,26 @@ def test_generate(): del directive.env.temp_data['autodoc:module'] del directive.env.ref_context['py:module'] + # test members with enum attributes + directive.env.ref_context['py:module'] = 'test_autodoc' + options.inherited_members = False + options.undoc_members = False + options.members = ALL + assert_processes([ + ('class', 'test_autodoc.EnumCls'), + ('attribute', 'test_autodoc.EnumCls.val1'), + ('attribute', 'test_autodoc.EnumCls.val2'), + ('attribute', 'test_autodoc.EnumCls.val3'), + ], 'class', 'EnumCls') + assert_result_contains( + ' :annotation: = 12', 'attribute', 'EnumCls.val1') + assert_result_contains( + ' :annotation: = 23', 'attribute', 'EnumCls.val2') + assert_result_contains( + ' :annotation: = 34', 'attribute', 'EnumCls.val3') + del directive.env.temp_data['autodoc:class'] + del directive.env.temp_data['autodoc:module'] + # test descriptor class documentation options.members = ['CustomDataDescriptor'] assert_result_contains('.. py:class:: CustomDataDescriptor(doc)', @@ -1020,6 +1041,18 @@ class InstAttCls(object): """Docstring for instance attribute InstAttCls.ia2.""" +class EnumCls(enum.Enum): + """ + this is enum class + """ + + #: doc for val1 + val1 = 12 + val2 = 23 #: doc for val2 + val3 = 34 + """doc for val3""" + + def test_type_hints(): from sphinx.ext.autodoc import formatargspec from sphinx.util.inspect import getargspec