FEA Integrate download links and binder/juputerlite buttons with pydata-sphinx-theme secondary sidebar

[Charlie-XIAO]

Given the popularity of pydata-sphinx-theme within the community nowadays, I'm requesting to see if it is possible to have some theme-specific configurations for better integration. In particular, pydata-sphinx-theme has a secondary sidebar where we can put the download links (Python source code and Jupyter notebook) and Binder/JupyterLite buttons. This way we no longer need the "Go to the end" note at the top and the footer at the bottom. This idea comes up when switching scikit-learn docs to pydata-sphinx-theme, see scikit-learn/scikit-learn#28415 for discussion and check its rendered docs here.

Is it possible to:

(1) Provide a configuration option to remove the top note and the footer.

(2) Expose API to get Binder/JupyterLite/download links (href) (and maybe badge image links (src) as well). I notice that there are things like interactive_example.gen_binder_url, but in particular I mean functions/variables added to the page context during sphinx build that can be directly called/accessed from Jinja templates (see the documentation). In this way users can easily create their own pydata-sphinx-theme components to put into the secondary sidebar.

Ideally, one can create templates like:

<div>
  <a href="{{ sg_binder_url }}">
    <img alt="Launch Binder" src="{{ sg_binder_badge_src }}">
  </a>
  <a href="{{ sg_lite_url }}">
    <img alt="Launch JupyterLite" src="{{ sg_lite_badge_src }}">
  </a>
</div>
{% endif %}

and

<div>
  <div title="{{ sg_python_name }}">
    <a download href="{{ sg_python_download_path }}">
      <i class="fa-solid fa-download"></i>
      Download source code
    </a>
</div>
<div>
  <div title="{{ sg_notebook_name }}">
    <a download href="{{ sg_notebook_download_path }}">
      <i class="fa-solid fa-download"></i>
      Download Jupyter notebook
    </a>
</div>

(3) An alternative to (2) is that, directly create pydata-sphinx-theme components (templates) and ship them with the library. Then figure out a way for pydata-sphinx-theme to discover that template (see the guide). This saves users' effort but I'm not sure if this is possible.

[larsoner]

For (1) so far we have just told people to do it with CSS because it's pretty easy (e.g., #1205).

For (2) and (3) your mock-up looks cool but I don't have a lot of insight into the best way to make it work. Maybe @drammock (who maintains pydata-sphinx-theme) would have some insight here.

[drammock]

I haven't thought very deeply about this yet, but off the cuff I would say option 3 is attractive if there's a way to make it work seamlessly for both PST sites and sites that use other themes. Sphinx has a templates_path variable (it's a list of paths) so SG could append its templates directory to that list, and the user could specify something like html_theme_options["secondary_sidebar_items"] = [..., "sg_py_download_link", "sg_nb_download_link", "sg_jupyterlite_launcher", "sg_binder_launcher"]. I think adding the relevant variables to the page context should be fairly straightforward (in SG's __init__.py, app.connect("html-page-context", name_of_a_function_that_defines_some_variables_for_in_page_use)). What I'm not clear on is how SG will know whether to write those elements in their current "default" locations (which users might want regardless of which theme they're using), or instead to not write the elements at all (because they'll already exist elsewhere in the page template).

That said, I think it's possible (though a bit ugly perhaps) to do the integration in the theme's code rather than here in sphinx-gallery. If sphinx-gallery can agree to coordinate with pydata-sphinx-theme on the stability of a few key CSS class names or HTML IDs, that might be enough. Then at the theme level, we can make components containing those elements (so users could place them where they wish) and the components could include some JS that would remove the element from it's default location where sphinx-gallery put it. I think that would be enough to get you both (1) and (2).