diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst index 9c742d059fc..b9af22d6f33 100644 --- a/doc/usage/extensions/imgconverter.rst +++ b/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 diff --git a/sphinx/ext/imgconverter.py b/sphinx/ext/imgconverter.py index a40b6c46a32..9d6708d2fa3 100644 --- a/sphinx/ext/imgconverter.py +++ b/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'