From 930056479febe148f860a4755db9ea3402d82c23 Mon Sep 17 00:00:00 2001 From: mxd4 Date: Sun, 24 Apr 2022 14:43:50 +0200 Subject: [PATCH 1/8] #10384 - Add comment on ImageMagick requirement --- doc/usage/extensions/imgconverter.rst | 2 +- tests/test_ext_imgconverter.py | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst index 9c742d059fc..89b12bddbda 100644 --- a/doc/usage/extensions/imgconverter.rst +++ b/doc/usage/extensions/imgconverter.rst @@ -12,7 +12,7 @@ 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. +Internally, this extension uses Imagemagick_ to convert images, you'll have to install it on your machine. .. _Imagemagick: https://www.imagemagick.org/script/index.php diff --git a/tests/test_ext_imgconverter.py b/tests/test_ext_imgconverter.py index 134947c8743..de13bffe46e 100644 --- a/tests/test_ext_imgconverter.py +++ b/tests/test_ext_imgconverter.py @@ -1,4 +1,6 @@ -"""Test sphinx.ext.imgconverter extension.""" +"""Test sphinx.ext.imgconverter extension. +Requires ImageMagick to be installed, otherwise the conversion will be skipped and this test will fail. +""" import os From 85524b58175fec2f961d619a358c33a2405f18c7 Mon Sep 17 00:00:00 2001 From: mxd4 Date: Mon, 2 May 2022 11:15:29 +0200 Subject: [PATCH 2/8] #10384 - Add line break to fix docslint --- doc/usage/extensions/imgconverter.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst index 89b12bddbda..c7bce9db441 100644 --- a/doc/usage/extensions/imgconverter.rst +++ b/doc/usage/extensions/imgconverter.rst @@ -12,7 +12,8 @@ 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, you'll have to install it on your machine. +Internally, this extension uses Imagemagick_ to convert images, +you'll have to install it on your machine. .. _Imagemagick: https://www.imagemagick.org/script/index.php From d2d5ce4eb6f9d947acde9a40814e7ab0b4461e60 Mon Sep 17 00:00:00 2001 From: mxd4 Date: Mon, 2 May 2022 11:29:11 +0200 Subject: [PATCH 3/8] #10384 - Changes after suggestions --- doc/usage/extensions/imgconverter.rst | 6 +++--- tests/test_ext_imgconverter.py | 5 ++++- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst index c7bce9db441..ce16b4fd9e1 100644 --- a/doc/usage/extensions/imgconverter.rst +++ b/doc/usage/extensions/imgconverter.rst @@ -12,10 +12,10 @@ 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, -you'll have to install it on your machine. +The extension uses ImageMagick_ to perform conversions, +and will fail if ImageMagick is not installed. -.. _Imagemagick: https://www.imagemagick.org/script/index.php +.. _ImageMagick: https://www.imagemagick.org .. note:: diff --git a/tests/test_ext_imgconverter.py b/tests/test_ext_imgconverter.py index de13bffe46e..1ce578f1807 100644 --- a/tests/test_ext_imgconverter.py +++ b/tests/test_ext_imgconverter.py @@ -1,5 +1,8 @@ """Test sphinx.ext.imgconverter extension. -Requires ImageMagick to be installed, otherwise the conversion will be skipped and this test will fail. + +Unix only. Fails if ImageMagick_ is not installed. + +.. _ImageMagick: https://imagemagick.org """ import os From 4d840c790c1b6f772ee8b9d94fbd961280eb16fe Mon Sep 17 00:00:00 2001 From: mxd4 Date: Mon, 2 May 2022 12:18:30 +0200 Subject: [PATCH 4/8] #10384 - Explicit warning and improve doc clarity --- doc/usage/extensions/imgconverter.rst | 16 +++++++++------- sphinx/ext/imgconverter.py | 9 ++++++--- 2 files changed, 15 insertions(+), 10 deletions(-) diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst index ce16b4fd9e1..e5039923be7 100644 --- a/doc/usage/extensions/imgconverter.rst +++ b/doc/usage/extensions/imgconverter.rst @@ -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 diff --git a/sphinx/ext/imgconverter.py b/sphinx/ext/imgconverter.py index a40b6c46a32..2b721a2bbeb 100644 --- a/sphinx/ext/imgconverter.py +++ b/sphinx/ext/imgconverter.py @@ -30,9 +30,12 @@ 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}!\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' From 4fc196a2a5e92fcb49e0ff1d7f6b327c584f34e7 Mon Sep 17 00:00:00 2001 From: mxd4 Date: Mon, 2 May 2022 12:26:16 +0200 Subject: [PATCH 5/8] #10384 - Fix flake8 --- doc/usage/extensions/imgconverter.rst | 2 +- sphinx/ext/imgconverter.py | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst index e5039923be7..e802d645758 100644 --- a/doc/usage/extensions/imgconverter.rst +++ b/doc/usage/extensions/imgconverter.rst @@ -32,7 +32,7 @@ Configuration .. confval:: image_converter - A path a conversion command. By default, the imgconverter finds + A path to a conversion command. By default, the imgconverter finds the command from search paths. On Unix platform, :command:`convert` command is used by default. diff --git a/sphinx/ext/imgconverter.py b/sphinx/ext/imgconverter.py index 2b721a2bbeb..10b3306230d 100644 --- a/sphinx/ext/imgconverter.py +++ b/sphinx/ext/imgconverter.py @@ -31,9 +31,10 @@ def is_available(self) -> bool: return True except OSError as 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"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 From 7f63a562b985abd6835c20934eff318e5bf6cd3d Mon Sep 17 00:00:00 2001 From: mxd4 Date: Mon, 2 May 2022 12:29:41 +0200 Subject: [PATCH 6/8] #10384 - Fix typo --- sphinx/ext/imgconverter.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/imgconverter.py b/sphinx/ext/imgconverter.py index 10b3306230d..a665ef3cf69 100644 --- a/sphinx/ext/imgconverter.py +++ b/sphinx/ext/imgconverter.py @@ -33,7 +33,7 @@ def is_available(self) -> bool: 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" + "Ensure it is installed, or set the 'image_converter' option " "to a custom conversion command.\n\n" f'Traceback: {exc}' )) From 33b5e23467f0d8b80e77012afc5992df1a0581b0 Mon Sep 17 00:00:00 2001 From: mxd4 Date: Mon, 2 May 2022 13:56:51 +0200 Subject: [PATCH 7/8] #10384 - Grammar --- doc/usage/extensions/imgconverter.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/usage/extensions/imgconverter.rst b/doc/usage/extensions/imgconverter.rst index e802d645758..b9af22d6f33 100644 --- a/doc/usage/extensions/imgconverter.rst +++ b/doc/usage/extensions/imgconverter.rst @@ -35,9 +35,9 @@ Configuration A path to a conversion command. By default, the imgconverter finds the command from search paths. - On Unix platform, :command:`convert` command is used by default. + On Unix platforms, the command :command:`convert` is used by default. - On Windows platform, :command:`magick` command is used by default. + On Windows, the command :command:`magick` is used by default. .. versionchanged:: 3.1 @@ -48,7 +48,7 @@ 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 From 8fc2178f1bb2850265cad39aac4cf4b1dbb964f7 Mon Sep 17 00:00:00 2001 From: mxd4 Date: Mon, 2 May 2022 18:05:15 +0200 Subject: [PATCH 8/8] #10384 - Remove comment in test --- sphinx/ext/imgconverter.py | 4 ++-- tests/test_ext_imgconverter.py | 7 +------ 2 files changed, 3 insertions(+), 8 deletions(-) diff --git a/sphinx/ext/imgconverter.py b/sphinx/ext/imgconverter.py index a665ef3cf69..9d6708d2fa3 100644 --- a/sphinx/ext/imgconverter.py +++ b/sphinx/ext/imgconverter.py @@ -31,8 +31,8 @@ def is_available(self) -> bool: return True except OSError as exc: logger.warning(__( - f"Unable to run the image conversion command {self.config.image_converter!r}!" - "\n'sphinx.ext.imgconverter' requires ImageMagick by default. " + 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}' diff --git a/tests/test_ext_imgconverter.py b/tests/test_ext_imgconverter.py index 1ce578f1807..134947c8743 100644 --- a/tests/test_ext_imgconverter.py +++ b/tests/test_ext_imgconverter.py @@ -1,9 +1,4 @@ -"""Test sphinx.ext.imgconverter extension. - -Unix only. Fails if ImageMagick_ is not installed. - -.. _ImageMagick: https://imagemagick.org -""" +"""Test sphinx.ext.imgconverter extension.""" import os