installation instructions button

[FoamyGuy]

Resolves: #1034

Make the download_instructions metadata field valid for CircuitPython core in addition to Blinka. If it has a value add a button linking to it to the download page.

I've only added the metadata to a single esp32 so far, but the rest of them could get updated to point to this guide if the way this has been added looks okay.

[FoamyGuy]

Maybe it should be inverted / outline only like the open installer button? So that there is only a single solid purple filled one?

[dhalbert]

Does the "Installation Instructions" link cover multiple possibilities? In that case maybe it shouldn't be a button like the others, but a link in the text above? Or, some distinct kind of button. Otherwise it looks like one of several similar choices.

[FoamyGuy]

@dhalbert I'm not sure if I understand what you mean all the way about covering multiple possibilities. But I think yes if I am understanding.

It will link to whatever value is in the board file's metadata for download_instructions. In the case of esp32 based devices as the initial issue was about that would go to the learn guide quickstart page for esp32 https://learn.adafruit.com/circuitpython-with-esp32-quick-start. For different devices it could conceivably be to a different guide page or even external resource if it's a 3rd party device documented elsewhere.

[FoamyGuy]

It currently matches the style that is used for the same concept on Blinka devices:

However it's not quite an 'apples to apples' comparison because there also is no download button or installer button.

[dhalbert]

I was thinking of distinguishing the "instructions" link from the data/action links:

The placement in these examples is not great, but I'm just trying to show some variations on style and placement.

[johnnohj]

(If I may contribute a suggestion)

[FoamyGuy]

Thanks @johnnohj I like the 'installation instructions' button up above the download links. I'll tinker with it today and try to get it shifted up to there.

[johnnohj]

Thanks @johnnohj I like the 'installation instructions' button up above the download links.

I was thinking about some way of ensuring the .uf2 button appears on line with the language selection and perhaps a note that indicates the .bin file is for advanced use cases? (At the very least, delete the reference to the .bin in my mock-up) The intention being to steer newer users to the .uf2 so they can nab the file and click through to the instructions without needing to navigate back because they downloaded the other.

(Edit: My assumption, of course, is that anyone there to download the .bin already has a pretty good idea what they're doing)

[FoamyGuy]

The latest commit moves this button to up above the download buttons and next to the release notes link:

It turns out that the width of the button originally was actually a tad larger than the width of the other download buttons in that column, which resulted in the arrow icon getting wrapped onto the next line down and looking weird. I reworded the button to use "INSTALL" instead of "INSTALLATION" to work around that.

I also changed the link to open in a new tab.

With regards to putting .UF2 above .BIN: As far as I can tell the order isn't specified anywhere currently. The order they appear in comes down to the order of their appearance in this list iteration:

circuitpython-org/_includes/download/board.html

Lines 134 to 136 in 59fe0d4

	{% for extension in version.extensions %}
	<a class="download-button {% if version.stable %}stable{% else %}unstable{% endif %} {{ extension }}" href="{{ download_url }}/en_US/adafruit-circuitpython-{{ board_id }}-en_US-{{ version.version }}.{{ extension }}">DOWNLOAD .{{ extension | upcase }} NOW <i class="fas fa-download" aria-hidden="true"></i></a>
	{% endfor %}

I can see the case for putting UF2 first, I know I certainly will always opt for that if it's available on a given device that I'm using.

I haven't given it extensive thought, but I think I would be in favor of swapping the order of them if there is no reason that will cause trouble or break something else. I do think it could be a seperate issue / PR from this one since it's not tied to the install instructions

[dhalbert]

How about "HOW TO INSTALL" as opposed to "INSTALL INSTRUCTIONS"?

I too think the .UF2 should be first.

[FoamyGuy]

"HOW TO INSTALL" fits nicely and I do think it's better than using "INSTRUCTIONS".

The latest commit changes to that.

I've created #1517 to track swapping the UF2 and BIN buttons. I think I have a relatively simple idea to implement it, if that works out I'll submit a seperate PR for it.

[dhalbert]

This is great! Thanks @johnnohj for the suggestions.