Merge branch '3.1.x' into 7807_contextmanager

CHANGES

@@ -7,6 +7,8 @@ Dependencies
 Incompatible changes
 --------------------
 
+* #7808: napoleon: a type for attribute are represented as typed field
+
 Deprecated
 ----------
 
@@ -21,9 +23,12 @@ 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
 * #7807: autodoc: wrong signature is shown for the function using contextmanager
 * #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 @@ class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # typ
         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 @@ class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):  # type:
         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):
@@ -1921,6 +1929,17 @@ class AttributeDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):
         else:
             self.add_line('   :annotation: %s' % self.options.annotation, sourcename)
 
+    def get_doc(self, encoding: str = None, ignore: int = None) -> List[List[str]]:
+        try:
+            # Disable `autodoc_inherit_docstring` temporarily to avoid to obtain
+            # a docstring from the value which descriptor returns unexpectedly.
+            # ref: https://github.com/sphinx-doc/sphinx/issues/7805
+            orig = self.env.config.autodoc_inherit_docstrings
+            self.env.config.autodoc_inherit_docstrings = False  # type: ignore
+            return super().get_doc(encoding, ignore)
+        finally:
+            self.env.config.autodoc_inherit_docstrings = orig  # type: ignore
+
     def add_content(self, more_content: Any, no_docstring: bool = False) -> None:
         if not self._datadescriptor:
             # if it's not a data descriptor, its docstring is very probably the

sphinx/ext/napoleon/__init__.py

@@ -168,10 +168,11 @@ class Config:
         **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 @@ class GoogleDocstring:
                 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 @@ class NamedtupleSubclassTest(BaseDocstringTest):
 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 @@ Attributes:
         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 @@ Attributes:
         actual = str(GoogleDocstring(docstring))
         expected = """\
 .. attribute:: in_attr
-   :type: numpy.ndarray
 
    super-dooper attribute
+
+   :type: numpy.ndarray
 """
         self.assertEqual(expected, actual)