Closes #3060: autodoc supports documentation for attributes of Enum class. Now autodoc render just the value of Enum attributes instead of Enum attribute representation.

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
 ----------

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

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."""

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