ENH integrate download/launcher links into `pydata-sphinx-theme` secondary sidebar by Charlie-XIAO · Pull Request #1312 · sphinx-gallery/sphinx-gallery

Charlie-XIAO · 2024-05-21T09:28:51Z

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 into pydata-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 adds get_download_links and get_launcher_links to per-page context which can be called in the jinja templates. Essentially they work by grabbing information from doctree, especially because I find no way to get the unique hash to the downloadable files (ref).
sphinx_gallery/components/: This path is appended to templates_path (ref). See html_theme_options.secondary_sidebar_items for an example usage with pydata-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 in pydata-sphinx-theme.
As suggested in FEA Integrate download links and binder/juputerlite buttons with pydata-sphinx-theme secondary 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 from doctree, 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).

…ary sidebar

larsoner

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 😬

sphinx_gallery/gen_gallery.py

Charlie-XIAO · 2024-05-25T01:29:08Z

I added a configuration option components_pattern (maybe it's not a good name). I know that sphinx-gallery already has plenty of configurations and may not want to add a new one, but the case here is:

# 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 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. See doc/conf.py. WDYT @larsoner?

Charlie-XIAO · 2024-05-25T02:24:38Z

Documentation also updated :)

larsoner

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.

sphinx_gallery/components/sg_launcher_links.html

sphinx_gallery/components/sg_download_links.html

larsoner · 2024-05-28T21:14:27Z

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!

Charlie-XIAO · 2024-05-29T08:53:06Z

Thanks for the review! I've updated the PR to:

Remove the components_pattern config option that is useful only in rare cases
Fix the failing tests (in particular how to deal with templates_path properly in older sphinx versions)
Move the docs to "advanced usage" since they are unrelated to "configuration options" now
Add tests to check that the sidebar links are consistent with the original links
Reword "Download both (zipped)" into "Download zipped". The reason is that the notebook is not always generated (e.g. the language is C++), so the word "both" may not always be proper.

larsoner

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

lucyleeow

LGTM, thanks this is a nice addition.
Nits only

doc/configuration.rst

doc/advanced.rst

Charlie-XIAO · 2024-05-30T06:31:10Z

Thanks for the reviews @larsoner @lucyleeow! I've resolved the conversations.

lucyleeow · 2024-05-31T00:53:36Z

Thank you @Charlie-XIAO !

lesteve · 2024-06-05T06:38:05Z

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.

GaelVaroquaux · 2024-06-05T07:07:20Z

+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)

ENH integrate download/launcher links into pydata-sphinx-theme second…

01d256c

…ary sidebar

larsoner added the enhancement label May 24, 2024

larsoner reviewed May 24, 2024

View reviewed changes

sphinx_gallery/gen_gallery.py Show resolved Hide resolved

Charlie-XIAO added 6 commits May 25, 2024 01:39

Merge remote-tracking branch 'upstream/master' into pst-integrate-links

1314ff2

resolve conversations

02af090

include the new download both link

7c92d58

include the new download both link

5787640

add an option for controlling which pages to add links

c0ba003

rename

98d4dfe

add documentation

e48dbc7

larsoner reviewed May 28, 2024

View reviewed changes

sphinx_gallery/components/sg_launcher_links.html Outdated Show resolved Hide resolved

sphinx_gallery/components/sg_download_links.html Outdated Show resolved Hide resolved

Charlie-XIAO added 11 commits May 29, 2024 08:28

Merge remote-tracking branch 'upstream/master' into pst-integrate-links

962abf7

use css classes

b75a663

different name

ea5cd4a

remove complexity

a38ee23

move docs

f8808fd

remove unused option

60ef041

fix for sphinx 5 and 6

3ebc309

update docs

ca94e2b

update docs

e4a6012

update tests

498c03d

rewording in docs

3db51a1

larsoner approved these changes May 29, 2024

View reviewed changes

lucyleeow approved these changes May 30, 2024

View reviewed changes

resolve conversations

d575df7

drammock mentioned this pull request May 30, 2024

Interactive documentation for Scientific Python projects scientific-python/summit-2024#19

Open

lucyleeow merged commit d4b29a6 into sphinx-gallery:master May 31, 2024

agriyakhetarpal mentioned this pull request Jun 1, 2024

DOC: Add interactive notebooks to pages in the "Usage Examples" section PyWavelets/pywt#741

Merged

3 tasks

Charlie-XIAO deleted the pst-integrate-links branch June 5, 2024 07:04

Charlie-XIAO mentioned this pull request Aug 22, 2024

DOC update sphinx-gallery 0.17.1 and remove our workaround scikit-learn/scikit-learn#29700

Merged

2 tasks

agriyakhetarpal mentioned this pull request Jan 27, 2025

Move notebook_modification_function functionality from Sphinx-Gallery to jupyterlite-sphinx, and a way forward for interactive notebooks #1427

Open

Conversation

Charlie-XIAO commented May 21, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Charlie-XIAO commented May 25, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Charlie-XIAO commented May 25, 2024

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

larsoner commented May 28, 2024

Uh oh!

Charlie-XIAO commented May 29, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

lucyleeow left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Charlie-XIAO commented May 30, 2024

Uh oh!

lucyleeow commented May 31, 2024

Uh oh!

lesteve commented Jun 5, 2024

Uh oh!

GaelVaroquaux commented Jun 5, 2024 via email

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Charlie-XIAO commented May 21, 2024 •

edited

Loading

Charlie-XIAO commented May 25, 2024 •

edited

Loading

Charlie-XIAO commented May 29, 2024 •

edited

Loading