doc: use imgconverter with imagemagick

[anscfrisson]

Solves warnings when running poetry run -- make -C doc pdf and for the CI doc-build step:

• 195c16b src/ansys/templates/python/common/{{cookiecutter.__project_name_slug}}/doc/source/conf.py: extensions: add: "sphinx.ext.imgconverter"

.../README.rst:: WARNING: a suitable image for latex builder not found: ['image/svg+xml'] (https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC)
.../README.rst:: WARNING: a suitable image for latex builder not found: ['image/svg+xml'] (https://codecov.io/gh/ansys/pysimba-library/branch/main/graph/badge.svg)
.../README.rst:: WARNING: a suitable image for latex builder not found: ['image/svg+xml'] (https://img.shields.io/badge/License-MIT-yellow.svg)
.../README.rst:: WARNING: a suitable image for latex builder not found: ['image/svg+xml'] (https://img.shields.io/badge/code%20style-black-000000.svg?style=flat)

• 198fe51 src/ansys/templates/python/common/{{cookiecutter.__project_name_slug}}/.github/workflows/ci_cd.yml: doc-build: dependencies: "imagemagick"

WARNING: Unable to run the image conversion command 'magick'. 'sphinx.ext.imgconverter' requires ImageMagick by default. Ensure it is installed, or set the 'image_converter' option to a custom conversion command.

Note: installing imagemagick (winget install imagemagick, sudo apt install imagemagick ...) is then necessary to run poetry run -- make -C doc pdf:

• 1f6a0f0 src/ansys/templates/python/*/{{cookiecutter.__project_name_slug}}/README.rst: add: Install imagemagick for image conversion

[RobPasMue]

LGTM! Letting final approval to @jorgepiloto

[jorgepiloto]

Awesome! Thanks @anscfrisson 🚀

[Revathyvenugopal162]

To ensure smoother operations, we implement the following code snippet in some of our libraries:

from sphinx.builders.latex import LaTeXBuilder 
LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"] 

This adjustment helps us avoid the necessity of installing ImageMagick. It's worth noting that due to differences in supported image types for HTML and PDF in Sphinx, SVG images occasionally cause issues.

i hope perhaps this could be helpful for libraries that prefer not to install ImageMagick.

[anscfrisson]

To ensure smoother operations, we implement the following code snippet in some of our libraries:

from sphinx.builders.latex import LaTeXBuilder 
LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"] 

This adjustment helps us avoid the necessity of installing ImageMagick. It's worth noting that due to differences in supported image types for HTML and PDF in Sphinx, SVG images occasionally cause issues.

i hope perhaps this could be helpful for libraries that prefer not to install ImageMagick.

@Revathyvenugopal162 Thanks for this solution that potentially brings less external requirements!

Could you please share the link to a repository where this is active and working?

I am finding at least 18 matches via https://github.com/search?q=org%3Aansys%20LaTeXBuilder%20&type=code but I'd rather try one that you would suggest.

I am asking since when I try to reproduce it with only the 2 above lines:
https://github.com/ansys-internal/simba-core/pull/7/commits/bfc5ed1b0d41f4978856d41f90b970c9ac4fcf09

diff --git a/doc/source/conf.py b/doc/source/conf.py
index d49cf7c..9dc870c 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -41,9 +41,13 @@ extensions = [
     "numpydoc",
     "sphinx.ext.intersphinx",
     "sphinx_copybutton",
-    "sphinx.ext.imgconverter",
+    # "sphinx.ext.imgconverter",
 ]

+from sphinx.builders.latex import LaTeXBuilder
+
+LaTeXBuilder.supported_image_types = ["image/png", "image/pdf", "image/svg+xml"]
+
 linkcheck_ignore = [r"https://tfs.ansys.com:\d+/"]

 # Intersphinx mapping

• doc building pipelines work on ubuntu https://github.com/ansys-internal/simba-core/actions/runs/8344317629/job/22836546940?pr=7
• but fail on my local windows machine: poetry run -- make -C doc pdf
  • successfully copies SVG files:

    copying images... [ 25%] https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwcopying images... [100%] https://img.shields.io/badge/code%20style-black-000000.svg?style=flat
    copying TeX support files... copying TeX support files...

  • but fails to compile with these images (excerpt):

    ! LaTeX Error: Unknown graphics extension: .svg.
    
    See the LaTeX manual or LaTeX Companion for explanation.
    Type  H <return>  for immediate help.
    ...
    
    l.86 ...82d4ee2a3732ce500caf7a76e902388e0dc}.svg}}

  • note: excerpts of the output including local settings:

    ...
    Running Sphinx v5.3.0
    ...
    Latexmk: This is Latexmk, John Collins, 31 Jan. 2024. Version 4.83.
    ...
    This is pdfTeX, Version 3.141592653-2.6-1.40.25 (MiKTeX 24.1) (preloaded format=pdflatex.fmt)
    restricted \write18 enabled.
    entering extended mode
    (ansys-simba-library.tex
    LaTeX2e <2023-11-01> patch level 1
    L3 programming layer <2024-01-04>
    (sphinxmanual.cls
    Document Class: sphinxmanual 2019/12/01 v2.3.0 Document class (Sphinx manual)
    (C:\Program Files\MiKTeX\tex/latex/base\report.cls
    Document Class: report 2023/05/17 v1.4n Standard LaTeX document class
    ...
    

I have been typesetting LaTeX documents with package svg. But it still requires external dependencies:

This bundle contains the two packages svg and svg-extract.

The svg package is intended for the automated integration of SVG graphics into LATEX documents. Therefore the capabilities provided by Inkscape — or more precisely its command line tool — are used to export the text within an SVG graphic to a separate file, which is then rendered by LATEX. For this purpose the two commands \includesvg and \includeinkscape are provided which are very similar to the \includegraphics command of the graphicx package.

In addition, the package svg-extract allows the extraction of these graphics into independent files in different graphic formats, exactly as it is rendered within the LATEX document, using either ImageMagick or Ghostscript.

And it does seem to be the solution employed, as I can only find a single match for "\usepackage{svg}" on org:ansys-internal : https://github.com/search?q=org%3Aansys-internal+%22%5Cusepackage%7Bsvg%7D%22&type=code

Another alternative to -sphinx.ext.imgconverter recommended in its documentation: https://www.sphinx-doc.org/en/master/usage/extensions/imgconverter.html#module-sphinx.ext.imgconverter

Note

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).

I would like to find a solution where we can debug doc pdf building locally on all Ansys-supported operating systems like Linux and Windows, with minimal external requirements (on Windows, installing imagemagick or Inkscape is simpler than having to setup docker, WSL, etc...).

What would be the impediments brought by installing imagemagick (on Linux?) ?

[Revathyvenugopal162]

@anscfrisson thanks for testing it.

1. If you have a package like \usepackage{svg} for LaTeX, you can use it within the options in conf.py as here
2. It doesn't fail in the Linux workflow because there's a PDF make command in your PDF where --interaction-stop-mode is on, so it won't interrupt if one image is not found or fails. This command can be found in the Makefile here, but it's not in the make.bat file here. You can add this command in the make.bat file like in pyansys-geometry, and it will work hopefully work

[anscfrisson]

@anscfrisson thanks for testing it.

1. If you have a package like \usepackage{svg} for LaTeX, you can use it within the options in conf.py as here
2. It doesn't fail in the Linux workflow because there's a PDF make command in your PDF where --interaction-stop-mode is on, so it won't interrupt if one image is not found or fails. This command can be found in the Makefile here, but it's not in the make.bat file here. You can add this command in the make.bat file like in pyansys-geometry, and it will work hopefully work

Thanks for your insights @Revathyvenugopal162 !

• Regarding 2.: I use git bash under Windows, which uses doc/Makefile, so I had -interaction=nonstopmode on. But the following line (test -f _build/latex/*.pdf && echo pdf exists) || exit 1 still made poetry run -- make -C doc pdf fail with make: *** [Makefile:34: pdf] Error 1. Thank you! That helped me figure out that I add subsequent errors unrelated to svg images that were blocking the creation of the PDF. Long story short, I had compilation errors such as The ec-qtmb source file could not be found. because I had not updated MikTeX packages at least once after its installation (or ran updmap as suggested in https://tex.stackexchange.com/questions/386430/pk-font-rtxmi-could-not-be-created).
• Regarding 1.: even if we add doc/source/conf.py with:

  latex_elements = {
      'extrapackages': r'\usepackage{svg}'
  }`
  

  we'd still have to modify sphinx internally to have \includesvg used for svg images instead of \includegraphics, as in Fix #1907: Support svg image in LaTeX output. sphinx-doc/sphinx#2166 (no SVG support in PDFs sphinx-doc/sphinx#1907): a PR that got closed in favor of using sphinx.ext.imgconverter as in this PR.

Now with this PR, we get README.rst badges typeset:

I understand that having badges in PDFs may not be deemed as important, but for simba-core (as in other potential projects) we may need to add architecture diagrams, and the best pivot format for editing and rendering/typesetting while preserving accessibility might be SVG.

From: sphinx.ext.imgconverter

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).

So 2 options to get SVG files properly typeset (rather than being skipped) in projects generated with ansys-templates:

• sphinx.ext.imgconverter with imagemagick that rasterizes images (this PR)
• sphinxcontrib-svg2pdfconverter (which uses Inkscape or rsvg-convert) with inkscape that keeps images vectorized (potential update of this PR)

If we already have to install bulky dependencies (such as MikTeX or texlive or basictex) to create PDF documentation, what is the issue with requiring either imagemagick or inkscape (that are both approved by Ansys)?

Making SVG support in ansys-templates an option might be cumbersome to implement.

What do you think about the above @Revathyvenugopal162 @RobPasMue @jorgepiloto ?

[RobPasMue]

I'd be fine installing this dependency (imagemagick or inkscape). I think it might be a good solution while we avoid having to implement the other extension which might be cumbersome