diff --git a/doc/source/conf.py b/doc/source/conf.py index afe5dc7a..4246a60a 100755 --- a/doc/source/conf.py +++ b/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) diff --git a/pyproject.toml b/pyproject.toml index ca31233a..7ae74ed8 100644 --- a/pyproject.toml +++ b/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",