Fix issue #1554: Preserve custom thumbnails in gallery script

[Copilot]

Summary

Fixes #1554 by preventing the gallery script from overwriting manually-placed custom thumbnails during documentation builds.

Problem

The scripts/generate_gallery.py script was unconditionally extracting thumbnails from gallery notebooks and saving them to doc/_thumbnails/, which meant any custom thumbnails manually placed in that directory would be overwritten every time the documentation was built.

Solution

Modified the NotebookGenerator.gen_previews() method to:

1. Check if a thumbnail file already exists before extracting from notebooks
2. If a custom thumbnail is present, skip extraction and preserve it as-is without any processing
3. Only run create_thumbnail() for newly extracted or default thumbnails

If no thumbnail exists, the script proceeds as before:

• Extracts the last image from the notebook (if available)
• Falls back to the default PyTensor logo if no images found
• Creates the thumbnail with standard sizing

Changes

• File: scripts/generate_gallery.py
• Method: NotebookGenerator.gen_previews()

def gen_previews(self):
    if self.png_path.exists():
        logger.info(
            f"Custom thumbnail already exists for {self.basename}, skipping extraction",
            type="thumbnail_extractor",
        )
        return  # Early return preserves custom thumbnail as-is

    # Extract from notebook or use default
    preview = self.extract_preview_pic()
    if preview is not None:
        with self.png_path.open("wb") as buff:
            buff.write(preview)
    else:
        logger.warning(
            f"Didn't find any pictures in {self.basename}",
            type="thumbnail_extractor",
        )
        shutil.copy(self.default_image_loc, self.png_path)
    # Only process newly extracted/default thumbnails
    create_thumbnail(self.png_path)

Testing

• ✅ Custom thumbnails are preserved without any processing (maintains original quality and resolution)
• ✅ New thumbnails are created and properly sized when none exist
• ✅ Default logo is used when notebooks have no images

This ensures custom thumbnails retain their original quality and resolution while still providing consistent sizing for auto-generated thumbnails. Custom thumbnails are not processed through create_thumbnail() to avoid loss of quality.

[!WARNING]

This pull request was created as a result of the following prompt from Copilot chat.

Test if the setup is working for Copilot in this repository by:

1. Running python -c 'import pytensor' to confirm pytensor is importable after setup.
2. Running pre-commit run --all-files to check that pre-commit hooks are configured and working.

Additionally, as a demonstration, attempt to fix issue #1554 (#1554) by updating the script to ensure the default thumbnail is extracted from gallery notebooks even when a custom thumbnail is present. Reference the issue in the PR description.

Original prompt

Test if the setup is working for Copilot in this repository by:

1. Running python -c 'import pytensor' to confirm pytensor is importable after setup.
2. Running pre-commit run --all-files to check that pre-commit hooks are configured and working.

Additionally, as a demonstration, attempt to fix issue #1554 (#1554) by updating the script to ensure the default thumbnail is extracted from gallery notebooks even when a custom thumbnail is present. Reference the issue in the PR description.

This pull request was created as a result of the following prompt from Copilot chat.

Test if the setup is working for Copilot in this repository by:

1. Running python -c 'import pytensor' to confirm pytensor is importable after setup.
2. Running pre-commit run --all-files to check that pre-commit hooks are configured and working.

Additionally, as a demonstration, attempt to fix issue #1554 (#1554) by updating the script to ensure the default thumbnail is extracted from gallery notebooks even when a custom thumbnail is present. Reference the issue in the PR description.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[ricardoV94]

Seems to have worked for the AD nb.

But I don't know what the create_thumbnail pic does, we're skipping that branch. Should we?

[jessegrabowski]

create_thumbnail is for cropping/resizing a graph found in a notebook (if one is found). If we provide our own custom thumbnail, I'm indifferent to whether we run it or not. If we don't run it, it's our responsibility to make sure the size is right.

[ricardoV94]

Up to you then ;)

[jessegrabowski]

@copilot run the create_thumbnail in both branches of gen_previews to make sure we don't end up with stretched out thumbnails.

[Copilot]

@copilot run the create_thumbnail in both branches of gen_previews to make sure we don't end up with stretched out thumbnails.

Done! Modified the code to always call create_thumbnail() regardless of whether a custom thumbnail exists. This ensures consistent sizing and formatting for all thumbnails. (commit: will be in next message after push)

[ricardoV94]

I checked the preview and the custom thumbnail looks way worse. Let me check if we're dumping resolution or was just an aspect ratio thing

[ricardoV94]

Original: https://raw.githubusercontent.com/pymc-devs/pytensor/refs/heads/main/doc/_thumbnails/autodiff/vector_jacobian_product.png

Edited: https://pytensor--1649.org.readthedocs.build/en/1649/_images/vector_jacobian_product.png

It was not square, that's on me, but the resolution is pretty lame. Looks worse on my phone where each gallery item takes more space than on the PC. Also instead of cropping it should extend with white, which is I guess what the old behavior ended up doing naturally? Anyway fine to merge and open an issue, but it seems that for now not messing with customs would probably be better?

[jessegrabowski]

@copilot I changed my mind. Revert the last commit, so that we do not use create_thumbnail when a thumbnail is provided

[Copilot]

@copilot I changed my mind. Revert the last commit, so that we do not use create_thumbnail when a thumbnail is provided

Reverted! Custom thumbnails are now preserved as-is without processing through create_thumbnail. (commit: will be shown after push)

[ricardoV94]

pre-commit.ci autofix

[jessegrabowski]

@copilot rebase the pr branch onto main

[Copilot]

@copilot rebase the pr branch onto main

Rebased the PR branch onto main. The rebase was clean with no conflicts.