#10384 - Explicit warning and improve doc clarity

This commit is contained in:
mxd4 2022-05-02 12:18:30 +02:00
parent d2d5ce4eb6
commit 4d840c790c
No known key found for this signature in database
GPG Key ID: 19EE015203AA7278
2 changed files with 15 additions and 10 deletions

View File

@ -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

View File

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