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

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

Browse Source 
Add comments on ImageMagick requirement
This commit is contained in:
Takeshi KOMIYA
2022-05-22 19:22:24 +09:00
committed by GitHub
parent dea4873a85 8fc2178f1b
commit cab2d93076
2 changed files with 17 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
doc/usage/extensions/imgconverter.rst
View File

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

10
sphinx/ext/imgconverter.py
View File

@@ -30,9 +30,13 @@ 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}. "
"'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'