ENH integrate download/launcher links into pydata-sphinx-theme secondary sidebar
#1312
Conversation
There was a problem hiding this comment.
Wow, doesn't actually seem all that complicated!
We'll definitely need an update to the docs showing how users can integrate this, though. Looks like the relevant stuff can be copy-pasted from doc/conf.py
Also I just merged #1299 which tweaked the download stuff a bit, hopefully that doesn't cause problems here 😬
|
I added a configuration option # This will cause the default templates (pagetoc, etc.) to be gone
html_theme_options.secondary_sidebar_items = {"auto_examples/*": [xxx]}
# auto_examples/* match multiple wildcard patterns which is invalid
# Moreover, I believe in most cases people want to add the templates to a whole gallery
# so it would almost always involve wildcard patterns
html_theme_options.secondary_sidebar_items = {"**": DEFAULTS, "auto_examples/*": [xxx]}By adding |
|
Documentation also updated :) |
There was a problem hiding this comment.
By adding components_pattern that accepts a list of glob patterns (same as what one would use for html_theme_options.secondary_sidebar_items), one can safely put sg_download_links and sg_launcher_links templates in a superset of the pages and then use components_pattern for restriction.
So the use case is that a project has, say, 3 galleries but only wants to enable it on 1 or 2 of them? If so then I'm not sure we actually need to support this. I'd rather assume YAGNI and go with a simpler implementation that is all-or-nothing.
|
Also looks like at least one failing test / build is related: https://github.com/sphinx-gallery/sphinx-gallery/actions/runs/9232232078/job/25403167870?pr=1312 But looks like good progress otherwise! |
|
Thanks for the review! I've updated the PR to:
|
There was a problem hiding this comment.
I checked a project build time and it seemed unaffected by the change which is great! And the rendered doc looks good.
@lucyleeow did you want to look? If not I'm happy to merge
|
Thanks for the reviews @larsoner @lucyleeow! I've resolved the conversations. |
|
Thank you @Charlie-XIAO ! |
|
Super nice to see this kind of improvements in sphinx-gallery, thanks everyone! For a bit of history, back in the days, there was an attempt at floating the buttons to the right #336 that I think eventually was reverted because the rendering looked off in some of sphinx themes. |
|
+1 on what Loïc said. This is a big deal in terms of usability, and usability is a big deal!
…On Jun 5, 2024, 08:38, at 08:38, "Loïc Estève" ***@***.***> wrote:
Super nice to see this kind of improvements in sphinx-gallery, thanks
everyone!
For a bit of history, back in the days, there was an attempt at
floating the buttons to the right
#336 that I think
eventually was reverted because the rendering looked off in some of
sphinx themes.
--
Reply to this email directly or view it on GitHub:
#1312 (comment)
You are receiving this because you are subscribed to this thread.
Message ID:
***@***.***>
|
… to version 0.17.0 v0.17.0 ------- Support for Python 3.8 and Sphinx 4 dropped in this release. Requirement is now Python >= 3.9 and Sphinx >= 5. **Implemented enhancements:** - Introduction tooltip corresponds to the first paragraph `#1344 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1344>`__ (`fgmacedo <https://github.com/fgmacedo>`__) - FIX Jupyterlite in CircleCI artifact `#1336 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1336>`__ (`lesteve <https://github.com/lesteve>`__) - MNT: Rename README.rst to GALLERY_HEADER.rst `#1321 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1321>`__ (`timhoffm <https://github.com/timhoffm>`__) - [ENH] Add custom thumbnails for failing examples `#1313 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1313>`__ (`tsbinns <https://github.com/tsbinns>`__) - ENH integrate download/launcher links into ``pydata-sphinx-theme`` secondary sidebar `#1312 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1312>`__ (`Charlie-XIAO <https://github.com/Charlie-XIAO>`__) - add option for zip downloads `#1299 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1299>`__ (`jamiecook <https://github.com/jamiecook>`__) - Allow setting animation format from gallery config `#1243 <https://github.com/sphinx-gallery/sphinx-gallery/pull/1243>`__ (`QuLogic <https://github.com/QuLogic>`__) (NEWS truncated at 15 lines)
Closes #1258.
This PR intends to integrate the download links (Python and Jupyter) and launcher badges (JupyterLite and Binder) into the secondary sidebar of
pydata-sphinx-theme. See the Basics Gallery with Matplotlib (here) for how it looks like. I'm not sure if this is the correct way to do in particular since it (may) currently fit only intopydata-sphinx-theme, but I think the template + component approach should in fact work with other themes (to some extent) as well. Regardless, I will explain a bit what this PR is doing:setup_pst_secondary_sidebar_links: This addsget_download_linksandget_launcher_linksto per-page context which can be called in the jinja templates. Essentially they work by grabbing information fromdoctree, especially because I find no way to get the unique hash to the downloadable files (ref).sphinx_gallery/components/: This path is appended totemplates_path(ref). Seehtml_theme_options.secondary_sidebar_itemsfor an example usage withpydata-sphinx-theme. It can also be used with e.g.html_sidebars(ref) but it is currently designed to best integrate with the secondary sidebar inpydata-sphinx-theme.pydata-sphinx-themesecondary sidebar #1258 (comment), removing the original download links and launcher badges can be done via CSS. And in fact since the components work by grabbing fromdoctree, they can indeed not be actually removed.@larsoner who involved in the original issue if you have time for a review.
A screenshot of this page:
I haven't added documentation or tests yet (the former I want to do after we do reach an agreement on this PR, the latter I'm not sure how to do 🤣 so some guidance is really appreciated).