Move download links to top of examples

[TimMonko]

References

During the pilot napari workshops, we observed new users having difficulty in navigating to the download buttons because of their location within the page.

Built on #1026. two-dot diff: https://github.com/TimMonko/docs/compare/shared-gallery-button-skin..TimMonko:docs:gallery-links

Description

This PR moves the download buttons to the top of the example by completely overriding the gallery insertion buttons and making our own button section which is shoved into the sphinx-gallery ready header.

To turn off the sphinx-gallery buttons we use css https://sphinx-gallery.github.io/stable/advanced.html#using-sphinx-gallery-sidebar-components

Perhaps this should be upstreamed to sphinx-gallery? It might be easier, but perhaps people aren't trying to have the download buttons be so obvious as we are, due to our drag and drop.

Present PR:

Original This PR:

[DragaDoncila]

Much prefer having the buttons on the top 🤩

[psobolewskiPhD]

ehh...
I dunno, i don't love it.
Can we at least have the description above the buttons?

I think first we should make clearer what to do with these links somewhere, e.g. address:

• Consider updating the examples gallery to suggest using napari <url of script> to run #852
• Add better instructions for running examples, e.g. to the Gallery landing page #678
  or even
• Binder runnable gallery notebooks #540

Not a blocker, just my opinion -- i might be missing some context, so feel free to ignore.

[Czaki]

Some conclusion? Should it land in 0.7.1

[psobolewskiPhD]

I took another look and to me the layout still looks wierd:

Title
<buttons>
Description
tags

I think it would look more purposeful, if the buttons were below the description or tags.
🤷

[DragaDoncila]

I think this should go into 0.7.1. It's true we can address a few other points to make running our examples easier, but I do think this is a strict improvement, and we know from users at the workshops that the old buttons were lost on the page. Happy to improve in future PRs as well!

[DragaDoncila]

I think it would look more purposeful, if the buttons were below the description or tags.

I can agree with this though. @TimMonko can we see what that looks like 🙏

[TimMonko]

I was a bit salty about trying to move it below the description, because I thought I had tried to troubleshoot that already. Turned out I missed the very useful "GENERATED FROM PYTHON SOURCE LINES" that exists after the tags and just before the script itself. I incorrectly thought that gen_rest.EXAMPLE_HEADER was the only repeated code present in the built .rst's.

So, I've moved the buttons below the description/tags and have updated the OP to reflect the change. I hope it's enough, because it's important to me that this is in the upcoming release so that it's ready for our July tutorials (in case following release is delayed)

[psobolewskiPhD]

The new look (top screenshot in OP) looks much better, for me anyways.
Thanks!