feat: resize all images to the same aspect ratio and format (#701)

* feat: resize all images to the same aspect ratio and format

* fix: rename script

* fix: remove unused image

* fix: vale issues

* Update doc/source/_static/thumbnails/README.md

Co-authored-by: Sébastien Morais <[email protected]>

* fix: reverting images

* feat: delete from _static folder

* feat: run on Sphinx build process

* feat: adapting conf.py to properly format it

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

---------

Co-authored-by: Sébastien Morais <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

doc/source/conf.py

@@ -2,8 +2,10 @@
 
 from datetime import datetime
 import os
+import subprocess
 
 from ansys_sphinx_theme import ansys_favicon, convert_version_to_pymeilisearch, get_version_match
+import sphinx
 from sphinx.builders.latex import LaTeXBuilder
 
 from pyansys import __version__ as pyansys_version
@@ -104,6 +106,12 @@
 user_agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0 Safari/537.36 Edg/123.0.2420.81"  # noqa: E501
 
 
+###########################################################################
+
+# -------------------------------------------------------------------------
+# Defining Sphinx build hooks
+# -------------------------------------------------------------------------
+
 ###########################################################################
 # Generate the package_versions directory
 ###########################################################################
@@ -348,14 +356,105 @@ def get_release_branches_in_metapackage():
     return ["main"] + release_branches, ["dev"] + versions
 
 
-# -------------------------------------------------------------------------
-# Execute the previous functions to generate the package_versions directory
-# -------------------------------------------------------------------------
+###########################################################################
+# Adapting thumbnails to the documentation
+###########################################################################
+# This section adapts the thumbnails to the documentation. The thumbnails
+# are resized to 640x480 pixels and centered on a white background.
+#
+# The script resizes all images in the _static/thumbnails directory to 640x480
+# pixels and saves the resized images in the same directory. After the
+# documentation build, the script reverts the changes to the thumbnails.
+
+
+def resize_with_background(input_image_path, output_image_path, target_size):
+    """Resize an image while maintaining aspect ratio and centering it on a white background.
+
+    Parameters
+    ----------
+    input_image_path : Path
+        The path to the input image.
+    output_image_path : Path
+        The path to save the output image.
+    target_size : tuple[int, int]
+        The target size of the output image as a tuple (width, height) in pixels.
+    """
+    from PIL import Image
+
+    # Open the input image
+    img = Image.open(input_image_path).convert("RGBA")  # Ensure the image has an alpha channel
+
+    # Resize the image while maintaining aspect ratio
+    img.thumbnail(target_size, Image.LANCZOS)
+
+    # Create a white background of the target size
+    background = Image.new(
+        "RGBA", target_size, (255, 255, 255, 255)
+    )  # White background with no transparency
+
+    # Calculate the position to center the resized image on the background
+    img_w, img_h = img.size
+    bg_w, bg_h = background.size
+    offset = ((bg_w - img_w) // 2, (bg_h - img_h) // 2)
+
+    # Paste the resized image onto the white background
+    background.paste(img, offset, mask=img)  # Use the image's transparency as a mask
+
+    # Convert the image to RGB to remove the alpha channel (no transparency)
+    background = background.convert("RGB")
+
+    # Save the result to the output path
+    background.save(output_image_path)
 
-branches, versions = get_release_branches_in_metapackage()
-generate_rst_files(
-    versions,
-    {version: build_versions_table(branch) for version, branch in zip(versions, branches)},
-)
 
 ###########################################################################
+
+# --------------------------------------------------------------------------
+# Sphinx build hooks
+# --------------------------------------------------------------------------
+
+
+def resize_thumbnails(app: sphinx.application.Sphinx):
+    """Resize all images in the current directory to 640x480 pixels."""
+    # Process all images
+    from pathlib import Path
+
+    thumbnail_dir = Path(__file__).parent.absolute() / "_static" / "thumbnails"
+
+    for image in thumbnail_dir.glob("*.png"):
+        target_size = (640, 480)
+        resize_with_background(image, image, target_size)
+
+
+def revert_thumbnails(app: sphinx.application.Sphinx, exception):
+    """Resize all images in the current directory to 640x480 pixels."""
+    from pathlib import Path
+
+    thumbnail_dir = Path(__file__).parent.absolute() / "_static" / "thumbnails"
+
+    subprocess.run(["git", "checkout", "--", thumbnail_dir])
+
+
+def package_versions_table(app: sphinx.application.Sphinx):
+    """Generate the package_versions directory."""
+    branches, versions = get_release_branches_in_metapackage()
+    generate_rst_files(
+        versions,
+        {version: build_versions_table(branch) for version, branch in zip(versions, branches)},
+    )
+
+
+def setup(app: sphinx.application.Sphinx):
+    """Run different hook functions during the documentation build.
+
+    Parameters
+    ----------
+    app : sphinx.application.Sphinx
+        Sphinx instance containing all the configuration for the documentation build.
+    """
+    # At the beginning of the build process - update the version in cheatsheet
+    app.connect("builder-inited", resize_thumbnails)
+    app.connect("builder-inited", package_versions_table)
+
+    # Reverting the thumbnails - no local changes
+    app.connect("build-finished", revert_thumbnails)

pyproject.toml

@@ -96,6 +96,7 @@ doc = [
     "Sphinx==8.0.2",
     "ansys-sphinx-theme==1.0.11",
     "Jinja2 ==3.1.4",
+    "Pillow==10.4.0",
     "PyGithub==2.4.0",
     "sphinx-copybutton==0.5.2",
     "sphinx-design==0.6.1",