DOC: Fix text tutorial thumbnails using sphinx_gallery_thumbnail_path#31224
DOC: Fix text tutorial thumbnails using sphinx_gallery_thumbnail_path#31224subhash-0000 wants to merge 6 commits intomatplotlib:mainfrom
Conversation
|
Thank you for opening your first PR into Matplotlib! If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks. You can also join us on gitter for real-time discussion. For details on testing, writing docs, and our review process, please see the developer guide. We strive to be a welcoming and open project. Please follow our Code of Conduct. |
|
Thanks for the PR, but users guide explain doesn't have thumbnails b/c there's no gallery there: https://matplotlib.org/devdocs/users/index.html Unless you meant https://matplotlib.org/devdocs/users/explain/text/index.html but annotation already has a thumbnail. |
|
Also this PR isn't doing anything: |
|
Hi @story645, thanks for the guidance. I've updated the PR to address both of your points: User Guide Index (users/index.html): You were right that this page felt bare. I've added thumbnails (Anatomy, Figure widgets, etc.) to the Quick start, Figure, and Text section cards using the :img-top: directive. This transforms the landing page into a visual 'gallery' entryway as requested. |
Please split this off into a separate PR as it's a separate discussion. Also why did you choose those?
We want to use the auto-generated plots b/c those are guaranteed to stay in sync. Which neither of these changes address that this PR does not fix the problem of missing thumbnails. |
29afed6 to
9e92390
Compare
|
Much improved, but now math text looks wonky. Also can you do something for fonts? Maybe the font fallback image that's already in the tutorial? |
doc/_static/mathtext_thumbnail.png
Outdated
doc/_static/usetex_tutorial.png
Outdated
There was a problem hiding this comment.
I would use the image in the tutorial, which is likely saved somewhere
There was a problem hiding this comment.
I've replaced it with a figure that matches the first image embedded in the tutorial — the cosine wave with the "TeX is Number" formula title, rendered via mathtext (no LaTeX required for the static image). If you'd prefer a different image from the tutorial, happy to swap it out
There was a problem hiding this comment.
I think the goal is no saved image/use the one that's already embedded in the file
c86d86a to
e65ad63
Compare
story645
left a comment
There was a problem hiding this comment.
I think for the linting errors, might be easier to just turn off liniting.
| Here is the standard example, | ||
| :doc:`/gallery/text_labels_and_annotations/tex_demo`: | ||
|
|
||
| .. figure:: /gallery/text_labels_and_annotations/images/sphx_glr_tex_demo_001.png |
There was a problem hiding this comment.
instead of saving a static image, can you point the thumbnail to this file too?
| sphinx_gallery_thumbnail_path = ( | ||
| 'gallery/text_labels_and_annotations/images/sphx_glr_tex_demo_001.png') |
There was a problem hiding this comment.
this isn't working so look at if we use the gallery paths for other thumbnails to see how this should be specified
947713f to
6002dec
Compare
doc/_static/usetex_tutorial.png
Outdated
There was a problem hiding this comment.
I think the goal is no saved image/use the one that's already embedded in the file
| # sphinx_gallery_thumbnail_path = ( | ||
| # 'gallery/text_labels_and_annotations/images/sphx_glr_tex_demo_001.png') |
There was a problem hiding this comment.
| # sphinx_gallery_thumbnail_path = ( | |
| # 'gallery/text_labels_and_annotations/images/sphx_glr_tex_demo_001.png') | |
| # sphinx_gallery_thumbnail_path = ( | |
| # '/gallery/text_labels_and_annotations/images/sphx_glr_tex_demo_001.png') |
this still isn't working, try more urls? Note, the path to the image should be relative to the conf.py
667a1e8 to
a1099ac
Compare
This PR fixes the missing thumbnails for the PGF, usetex, and annotations tutorials in the "User Guide / Explain" section.
Why is this change necessary? These tutorials are currently showing the default Matplotlib logo placeholder instead of actual thumbnails. This happens because these examples rely on external dependencies (like LaTeX or specific backends) that may not be available during the automated documentation build process.
What problem does it solve? Setting sphinx_gallery_thumbnail_number is ineffective when no figures are generated during the build. This change implements the correct solution by using sphinx_gallery_thumbnail_path to point to pre-existing static images.
What is the reasoning for this implementation?
Researched the codebase and found that high-quality static thumbnails for these tutorials (e.g., pgf_preamble.png, usetex_tutorial.png) already exist in doc/_static/.
Found that the tutorial files originally had commented-out lines for these paths.
Uncommenting and correctly implementing these paths ensures the gallery shows valid thumbnails regardless of whether the backend is active during the build.
Closes #17479 (Addresses the Text tutorial portion of the tracking issue).
AI Disclosure
I used the Antigravity AI assistant to help identify the technical distinction between thumbnail_number and thumbnail_path and to help locate the existing static image assets within the Matplotlib directory structure.
PR checklist
"closes #17479" is in the body of the PR description
[N/A] new and changed code is tested
[N/A] Plotting related features are demonstrated in an example
[N/A] New Features and API Changes are noted with a directive and release note