DOC: Clarify SVG hyperlink behavior in gallery hyperlinks example#31497
DOC: Clarify SVG hyperlink behavior in gallery hyperlinks example#31497jayaprajapatii wants to merge 5 commits intomatplotlib:mainfrom
Conversation
timhoffm
left a comment
There was a problem hiding this comment.
This is not the intended solution for #31452
Instead, we want to show the SVG images. There are to possible approaches
- the difficult one: make sphinx-gallery (optionally) support creating SVG output.
- the hacked one: render the SVG image locally and add it as a static image to the example.
|
@timhoffm Thanks for the clarification! I understand that the goal is to actually show the SVG output rather than just explain the behavior. I’ll work on implementing the second approach by rendering the SVG locally and adding it as a static image to the example. |
timhoffm
left a comment
There was a problem hiding this comment.
Missing svg files and inappropirate comment location/(maybe) content.
Please take more care in veryifing the result of your changes.
| # NOTE: | ||
| # Hyperlinks in SVG output may not appear interactive in the documentation | ||
| # because Sphinx renders SVGs as static images (<img> tags), | ||
| # so hyperlinks are not clickable | ||
| # The SVG images are shown below. | ||
| # To see working hyperlinks, open the generated SVG file directly in a browser. | ||
|
|
There was a problem hiding this comment.
This renders as a comment in the code, which is not appropriate. Instead it should be regular example text.
Also, I'm not clear whether the content is correct. If we show the svgs here, is it still needed to open the files separately in a browser?
timhoffm
left a comment
There was a problem hiding this comment.
Again, I urge you to validate your proposals locally before pushing to a public PR. - Or at the very least mark your PR as draft until you are sure it does the right thing.
Posting half-baked PRs causes unnecessary reviewer effort. In the interest of project health, we can only tolerate so much of this. Continued deficits in PR quality may lead to closure.
| # %% | ||
| # Display generated SVGs in docs | ||
| # | ||
| # .. image:: scatter.svg |
There was a problem hiding this comment.
The SVGs do not appear in the documentation. Likely because the generated .rst source file are in a different place than the .py. So the files cannot be found. See also https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#images
|
@timhoffm Thank you for pointing this out, and sorry for not validating the changes properly before pushing. I now understand the issue with SVGs not appearing due to incorrect paths. I'll fix this and verify the documentation locally before updating the PR. |
|
Hello @timhoffm
The outputs are now visible in the documentation. Please let me know if anything still needs improvement. |
|
I don't understand what's happening here. Can you explain this?
Additionally, we want the SVGs embedded into the HTML, not PNGs as they don't expose the hyperlinks. |
Closes #31452
Summary
Show the generated SVG outputs in the hyperlinks example by including them in the documentation.
Problem
The example generated SVG files with hyperlinks, but they are not visible in the documentation, which makes the output unclear.
Solution
The example still generates SVG files as before.
Since Sphinx renders SVGs as static images, the documentation now displays the rendered outputs (static images) so that the results are visible.
Impact