From 4d840c790c1b6f772ee8b9d94fbd961280eb16fe Mon Sep 17 00:00:00 2001
From: mxd4 <maxime_droy@ultimatesoftware.com>
Date: Mon, 2 May 2022 12:18:30 +0200
Subject: [PATCH] #10384 - Explicit warning and improve doc clarity

---
 doc/usage/extensions/imgconverter.rst | 16 +++++++++-------
 sphinx/ext/imgconverter.py            |  9 ++++++---
 2 files changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst
index ce16b4fd9..e5039923b 100644
--- a/doc/usage/extensions/imgconverter.rst
+++ b/doc/usage/extensions/imgconverter.rst
@@ -12,14 +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.
 
-The extension uses ImageMagick_ to perform conversions,
-and will fail if ImageMagick is not installed.
+By default the extension uses ImageMagick_ to perform conversions,
+and will not work if ImageMagick is not installed.
 
 .. _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``).
@@ -32,10 +32,12 @@ Configuration
 
 .. confval:: image_converter
 
-   A path to :command:`convert` command.  By default, the imgconverter uses
+   A path 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 platform, :command:`convert` command is used by default.
+
+   On Windows platform, :command:`magick` command is used by default.
 
    .. versionchanged:: 3.1
 
@@ -46,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 platform, it defaults to ``["convert"]``.
 
    .. versionchanged:: 3.1
 
-      Use ``["convert"]`` by default on windows
+      Use ``["convert"]`` by default on Windows
diff --git a/sphinx/ext/imgconverter.py b/sphinx/ext/imgconverter.py
index a40b6c46a..2b721a2bb 100644
--- a/sphinx/ext/imgconverter.py
+++ b/sphinx/ext/imgconverter.py
@@ -30,9 +30,12 @@ class ImagemagickConverter(ImageConverter):
             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}!\n"
+                "'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'