search

ansys / ansys-templates

A tool for creating new projects according to Ansys guidelines
https://templates.ansys.com
MIT License
11 stars 4 forks source link

doc: use imgconverter with imagemagick #455

Open anscfrisson opened 4 months ago

anscfrisson commented 4 months ago

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

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

Revathyvenugopal162 commented 4 months ago

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 commented 4 months ago

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

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 commented 4 months ago

@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 commented 3 months ago

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

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

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:

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 commented 3 months ago

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