Merge branch '5.0.x' into 5.x

CHANGES

@@ -41,6 +41,7 @@ Bugs fixed
   ``autodoc_typehints="description"``
 * #9648: autodoc: ``*args`` and ``**kwargs`` entries are duplicated when
   ``autodoc_typehints="description"``
+* #8180: autodoc: Docstring metadata ignored for attributes
 * #10443: epub: EPUB builder can't detect the mimetype of .webp file
 * #10456: py domain: ``:meta:`` fields are displayed if docstring contains two
   or more meta-field

doc/usage/extensions/imgconverter.rst

@@ -12,13 +12,14 @@ This extension converts images in your document to appropriate format for
 builders.  For example, it allows you to use SVG images with LaTeX builder.
 As a result, you don't mind what image format the builder supports.
 
-Internally, this extension uses Imagemagick_ to convert images.
+By default the extension uses ImageMagick_ to perform conversions,
+and will not work if ImageMagick is not installed.
 
-.. _Imagemagick: https://www.imagemagick.org/script/index.php
+.. _ImageMagick: https://www.imagemagick.org
 
 .. note::
 
-   Imagemagick rasterizes a SVG image on conversion.  As a result, the image
+   ImageMagick rasterizes a SVG image on conversion.  As a result, the image
    becomes not scalable.  To avoid that, please use other image converters like
    `sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or
    ``rsvg-convert``).
@@ -31,10 +32,12 @@ Configuration
 
 .. confval:: image_converter
 
-   A path to :command:`convert` command.  By default, the imgconverter uses
+   A path to a conversion command.  By default, the imgconverter finds
    the command from search paths.
 
-   On windows platform, :command:`magick` command is used by default.
+   On Unix platforms, the command :command:`convert` is used by default.
+
+   On Windows, the command :command:`magick` is used by default.
 
    .. versionchanged:: 3.1
 
@@ -45,8 +48,8 @@ Configuration
    Additional command-line arguments to give to :command:`convert`, as a list.
    The default is an empty list ``[]``.
 
-   On windows platform, it defaults to ``["convert"]``.
+   On Windows, it defaults to ``["convert"]``.
 
    .. versionchanged:: 3.1
 
-      Use ``["convert"]`` by default on windows
+      Use ``["convert"]`` by default on Windows

sphinx/ext/autodoc/importer.py

@@ -280,12 +280,19 @@ def get_class_members(subject: Any, objpath: List[str], attrgetter: Callable
                     members[name] = ObjectMember(name, INSTANCEATTR, class_=cls,
                                                  docstring=docstring)
 
-            # append instance attributes (cf. self.attr1) if analyzer knows
+            # append or complete instance attributes (cf. self.attr1) if analyzer knows
             if analyzer:
                 for (ns, name), docstring in analyzer.attr_docs.items():
                     if ns == qualname and name not in members:
+                        # otherwise unknown instance attribute
                         members[name] = ObjectMember(name, INSTANCEATTR, class_=cls,
                                                      docstring='\n'.join(docstring))
+                    elif (ns == qualname and docstring and
+                          isinstance(members[name], ObjectMember) and
+                          not members[name].docstring):
+                        # attribute is already known, because dir(subject) enumerates it.
+                        # But it has no docstring yet
+                        members[name].docstring = '\n'.join(docstring)
     except AttributeError:
         pass
 

sphinx/ext/imgconverter.py

@@ -30,9 +30,13 @@ def is_available(self) -> bool:
             subprocess.run(args, stdout=PIPE, stderr=PIPE, check=True)
             return True
         except OSError as exc:
-            logger.warning(__('convert command %r cannot be run, '
-                              'check the image_converter setting: %s'),
-                           self.config.image_converter, exc)
+            logger.warning(__(
+                f"Unable to run the image conversion command {self.config.image_converter!r}. "
+                "'sphinx.ext.imgconverter' requires ImageMagick by default. "
+                "Ensure it is installed, or set the 'image_converter' option "
+                "to a custom conversion command.\n\n"
+                f'Traceback: {exc}'
+            ))
             return False
         except CalledProcessError as exc:
             logger.warning(__('convert exited with error:\n'

tests/roots/test-ext-autodoc/target/private.py

@@ -13,3 +13,15 @@ def _public_function(name):
 
 PRIVATE_CONSTANT = None  #: :meta private:
 _PUBLIC_CONSTANT = None  #: :meta public:
+
+
+class Foo:
+    #: A public class attribute whose name starts with an underscore.
+    #:
+    #: :meta public:
+    _public_attribute = 47
+
+    #: A private class attribute whose name does not start with an underscore.
+    #:
+    #: :meta private:
+    private_attribute = 11

tests/test_ext_autodoc_private_members.py

@@ -102,3 +102,57 @@ def test_private_members(app):
         '   :meta public:',
         '',
     ]
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_private_attributes(app):
+    app.config.autoclass_content = 'class'
+    options = {"members": None}
+    actual = do_autodoc(app, 'class', 'target.private.Foo', options)
+    assert list(actual) == [
+        '',
+        '.. py:class:: Foo()',
+        '   :module: target.private',
+        '',
+        '',
+        '   .. py:attribute:: Foo._public_attribute',
+        '      :module: target.private',
+        '      :value: 47',
+        '',
+        '      A public class attribute whose name starts with an underscore.',
+        '',
+        '      :meta public:',
+        '',
+    ]
+
+
+@pytest.mark.sphinx('html', testroot='ext-autodoc')
+def test_private_attributes_and_private_members(app):
+    app.config.autoclass_content = 'class'
+    options = {"members": None,
+               "private-members": None}
+    actual = do_autodoc(app, 'class', 'target.private.Foo', options)
+    assert list(actual) == [
+        '',
+        '.. py:class:: Foo()',
+        '   :module: target.private',
+        '',
+        '',
+        '   .. py:attribute:: Foo._public_attribute',
+        '      :module: target.private',
+        '      :value: 47',
+        '',
+        '      A public class attribute whose name starts with an underscore.',
+        '',
+        '      :meta public:',
+        '',
+        '',
+        '   .. py:attribute:: Foo.private_attribute',
+        '      :module: target.private',
+        '      :value: 11',
+        '',
+        '      A private class attribute whose name does not start with an underscore.',
+        '',
+        '      :meta private:',
+        '',
+    ]