DOC [PST] disable gallery link tweaks when html-noplot to avoid warnings
#28512
Conversation
doc/sphinxext/move_gallery_links.py
Outdated
| @@ -141,22 +145,31 @@ def _create_badge_link(link): | |||
| # These will be removed at the end if new links are successfully created | |||
| sg_note = soup.find("div", class_="sphx-glr-download-link-note") | |||
| sg_footer = soup.find("div", class_="sphx-glr-footer") | |||
| assert sg_note is not None, "Failed to find the top note" | |||
| assert sg_footer is not None, "Failed to find the gallery footer" | |||
There was a problem hiding this comment.
I have the feeling that those assertions might still fail if we run some examples, but not all via the EXAMPLES_PATTERN env variable: https://scikit-learn.org/stable/developers/contributing.html#building-the-documentation
Can you please check?
There was a problem hiding this comment.
Ah didn't notice that because in make.bat we did not have this option. I will take a look (maybe a bit later).
There was a problem hiding this comment.
I removed everything and built from scratch on my local machine with html-noplot, but it seems that I did not get those errors?
Then I looked at the sphinx-gallery source code: in the save_rst_example function no matter whether the example is run or not the components we tweak will be added.
Is it possible that we are using different versions of sphinx-gallery (mine is 0.15.0)? Or can you please provide more context on your side @ogrisel?
There was a problem hiding this comment.
Let me try again with a clean environment and recent versions of everything.
There was a problem hiding this comment.
So I created a new env with the latest sphinx-gallery (0.15.0) and ran make html-noplot and I can reproduce the WARNING: Failed to tweak gallery links in... warnings I initially reported in #28331 (comment).
Also, I tried this branch and the warning go away. But it seems that I can no longer get the EXAMPLES_PATTERN thing to work. For instance I tried EXAMPLES_PATTERN=".*mean.*" make html-noplot and I did not get the plot generated in plot_kmeans_stability_low_dim_dense.html. I don't remember how it's supposed to work. But doing experiment is very slow. It seems that make html-noplot is much slower than it used to be. We would need to profile to find why it's the case. Note: I have not yet tried on main, maybe the slowness is already there.
There was a problem hiding this comment.
So I created a new env with the latest sphinx-gallery (0.15.0) and ran
make html-noplotand I can reproduce theWARNING: Failed to tweak gallery links in...warnings I initially reported in #28331 (comment).
Thanks for experimenting! Then there might some mistakes made on my side. I will take another look into it some time.
Also, I atried this branch and the warning go away. But it seems that I can no longer get the
EXAMPLES_PATTERNthing to work. For instance I triedEXAMPLES_PATTERN=".*mean.*" make html-noplotand I did not get the plot generated inplot_kmeans_stability_low_dim_dense.html. I don't remember how it's supposed to work.
Hmm that's strange. I don't think it's likely caused by this PR because tweak_gallery_links is just a post transform that executes in the very last step while plot generation is determined very early even before page generation. I will try to test this as well.
But doing experiment is very slow. It seems that
make html-noplotis much slower than it used to be. We would need to profile to find why it's the case. Note: I have not yet tried onmain, maybe the slowness is already there.
I also noticed the significant slowdown (as long as using pydata-sphinx-theme): not 100% sure but it may be caused by pydata/pydata-sphinx-theme#1643.
|
Thinking over again, I think we may not really need to care about all those corner cases simply because there are too many of them. For instance, My current idea is: If we can tweak then we do it, otherwise leave it as is (without warning). The thing is, at worst we failed to tweak but since the links will still be there (in the original position) it is not really a big issue. Moreover, if this post transform really fails some day, most probably all pages will fail (instead of only some pages failing) then it is easy to discover by just looking at a random gallery page in the website. WDYT @ogrisel? |
Let's do the latter. |
Please note that this PR targets the
new_web_themebranch!Towards #28084. For context see #28331 (comment). In short, when built without running gallery examples (
make html-noplot) the badge links and download links could be missing; we do not want to tweak them then. This PR also improves the warning messages a bit.@ogrisel