Merge pull request sphinx-doc#10386 from mxd4/10384-comment-img-magick

Add comments on ImageMagick requirement

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