Merge branch '3.1.x' into 7805_retval_of_descriptors

CHANGES

@@ -7,6 +7,8 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #7808: napoleon: a type for attribute are represented as typed field
+
 Deprecated
 ----------
 
@@ -18,9 +20,11 @@ Bugs fixed
 
 * #7808: autodoc: Warnings raised on variable and attribute type annotations
 * #7802: autodoc: EOFError is raised on parallel build
+* #7821: autodoc: TypeError is raised for overloaded C-ext function
 * #7805: autodoc: an object which descriptors returns is unexpectedly documented
 * #7812: autosummary: generates broken stub files if the target code contains
   an attribute and module that are same name
+* #7808: napoleon: Warnings raised on variable and attribute type annotations
 * #7811: sphinx.util.inspect causes circular import problem
 
 Testing

sphinx/ext/autodoc/__init__.py

@@ -1237,7 +1237,11 @@ def annotate_to_first_argument(self, func: Callable, typ: Type) -> None:
         params = list(sig.parameters.values())
         if params[0].annotation is Parameter.empty:
             params[0] = params[0].replace(annotation=typ)
-            func.__signature__ = sig.replace(parameters=params)  # type: ignore
+            try:
+                func.__signature__ = sig.replace(parameters=params)  # type: ignore
+            except TypeError:
+                # failed to update signature (ex. built-in or extension types)
+                return
 
 
 class SingledispatchFunctionDocumenter(FunctionDocumenter):
@@ -1833,7 +1837,11 @@ def annotate_to_first_argument(self, func: Callable, typ: Type) -> None:
         params = list(sig.parameters.values())
         if params[1].annotation is Parameter.empty:
             params[1] = params[1].replace(annotation=typ)
-            func.__signature__ = sig.replace(parameters=params)  # type: ignore
+            try:
+                func.__signature__ = sig.replace(parameters=params)  # type: ignore
+            except TypeError:
+                # failed to update signature (ex. built-in or extension types)
+                return
 
 
 class SingledispatchMethodDocumenter(MethodDocumenter):

sphinx/ext/napoleon/__init__.py

@@ -168,10 +168,11 @@ def __unicode__(self):
         **If False**::
 
             .. attribute:: attr1
-               :type: int
 
                Description of `attr1`
 
+               :type: int
+
     napoleon_use_param : :obj:`bool` (Defaults to True)
         True to use a ``:param:`` role for each function parameter. False to
         use a single ``:parameters:`` role for all the parameters.

sphinx/ext/napoleon/docstring.py

@@ -588,12 +588,13 @@ def _parse_attributes_section(self, section: str) -> List[str]:
                 lines.append('.. attribute:: ' + _name)
                 if self._opt and 'noindex' in self._opt:
                     lines.append('   :noindex:')
-                if _type:
-                    lines.extend(self._indent([':type: %s' % _type], 3))
                 lines.append('')
 
                 fields = self._format_field('', '', _desc)
                 lines.extend(self._indent(fields, 3))
+                if _type:
+                    lines.append('')
+                    lines.extend(self._indent([':type: %s' % _type], 3))
                 lines.append('')
         if self._config.napoleon_use_ivar:
             lines.append('')

tests/test_ext_napoleon_docstring.py

@@ -53,19 +53,22 @@ def test_attributes_docstring(self):
 Sample namedtuple subclass
 
 .. attribute:: attr1
-   :type: Arbitrary type
 
    Quick description of attr1
 
+   :type: Arbitrary type
+
 .. attribute:: attr2
-   :type: Another arbitrary type
 
    Quick description of attr2
 
+   :type: Another arbitrary type
+
 .. attribute:: attr3
-   :type: Type
 
    Adds a newline after the type
+
+   :type: Type
 """
 
         self.assertEqual(expected, actual)
@@ -409,9 +412,10 @@ def test_attributes_with_class_reference(self):
         actual = str(GoogleDocstring(docstring))
         expected = """\
 .. attribute:: in_attr
-   :type: :class:`numpy.ndarray`
 
    super-dooper attribute
+
+   :type: :class:`numpy.ndarray`
 """
         self.assertEqual(expected, actual)
 
@@ -423,9 +427,10 @@ def test_attributes_with_class_reference(self):
         actual = str(GoogleDocstring(docstring))
         expected = """\
 .. attribute:: in_attr
-   :type: numpy.ndarray
 
    super-dooper attribute
+
+   :type: numpy.ndarray
 """
         self.assertEqual(expected, actual)