IntenseWebs/sphinx
3
0
Fork 0
mirror of https://github.com/sphinx-doc/sphinx.git synced 2025-02-25 18:55:22 -06:00
Code Issues Packages Projects Releases Wiki Activity

#10384 - Explicit warning and improve doc clarity

Browse Source
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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
doc/usage/extensions/imgconverter.rst
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. 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. As a result, you don't mind what image format the builder supports.
The extension uses ImageMagick_ to perform conversions, By default the extension uses ImageMagick_ to perform conversions,
and will fail if ImageMagick is not installed. and will not work if ImageMagick is not installed.
.. _ImageMagick: https://www.imagemagick.org .. _ImageMagick: https://www.imagemagick.org
.. note:: .. 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 becomes not scalable. To avoid that, please use other image converters like
`sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or `sphinxcontrib-svg2pdfconverter`__ (which uses Inkscape or
``rsvg-convert``). ``rsvg-convert``).
@ -32,10 +32,12 @@ Configuration
.. confval:: image_converter .. 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. 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 .. versionchanged:: 3.1
@ -46,8 +48,8 @@ Configuration
Additional command-line arguments to give to :command:`convert`, as a list. Additional command-line arguments to give to :command:`convert`, as a list.
The default is an empty list ``[]``. The default is an empty list ``[]``.
On windows platform, it defaults to ``["convert"]``. On Windows platform, it defaults to ``["convert"]``.
.. versionchanged:: 3.1 .. versionchanged:: 3.1
Use ``["convert"]`` by default on windows Use ``["convert"]`` by default on Windows

9
sphinx/ext/imgconverter.py
View File

@ -30,9 +30,12 @@ class ImagemagickConverter(ImageConverter):
subprocess.run(args, stdout=PIPE, stderr=PIPE, check=True) subprocess.run(args, stdout=PIPE, stderr=PIPE, check=True)
return True return True
except OSError as exc: except OSError as exc:
logger.warning(__('convert command %r cannot be run, ' logger.warning(__(
'check the image_converter setting: %s'), f"Unable to run the image conversion command {self.config.image_converter!r}!\n"
self.config.image_converter, exc) "'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 return False
except CalledProcessError as exc: except CalledProcessError as exc:
logger.warning(__('convert exited with error:\n' logger.warning(__('convert exited with error:\n'