Use stable version for dev docs bundle links

[TimMonko]

References and relevant issues

Closes #969

Description

Instead of just the raw release link, which can be broken for dev releases (i.e. 0.7.1dev#sha) this changes it so that
It will be the latest stable release.

To do this, I have it check whether the current ref is a prerelease, and if it is, then it checks version_switcher.json for the entry with "preferred" and returns it's "version". Thus both 0.7.1rc0 and 0.7.1dev+hash will point back to the preferred version (0.7.0).

Then, when a new stable release is pushed, the ref is no longer a pre-release and will instead use the version string (which I think in all cases is X.Y.Z from how I read the code) so releasing 0.7.1 should use 0.7.1 for the links, despite the version_switcher not yet being updated.

I also slightly updated the Mac buttons and install section so that it cleared up uncertainty re: the intro-workshop download

[TimMonko]

@psobolewskiPhD here also is where I mention arm64 and Apple Silicon.

I've never used mac so I genuinely don't know the correct answer here.

[psobolewskiPhD]

Yeah same issue. I think linking the apple docs is probably the best, but otherwise we could try
(M- or A-series) or something like that.

[Czaki]

For me this logic is not fixing pointed issue.

I think that we need to use function like this:

def get_latest_released_version(version_: packaging.version.Version) -> str:
    version_ = version_.__replace__(local=None)
    if not version_.is_devrelease:
        return str(version_)
    if version_.pre is None:
        # we are on path with no pre-release
        assert version_.micro > 0, "dev release must have micro > 0"
        return f'{version_.major}.{version_.minor}.{version_.micro - 1}'

    # we are on path with pre-release
    pre_label, pre_number = version_.pre
    return str(version_.__replace__(pre=(pre_label, pre_number - 1), dev=None))

[willingc]

Thanks @TimMonko

[Czaki]

https://napari.zulipchat.com/#narrow/channel/585967-napari-workshop-2026-04-01/topic/Installation.20Questions.20and.20Troubleshooting/near/583551942

[willingc]

@TimMonko A general question. How would you feel about dev docs displaying the stable released bundle? Perhaps adding a comment that pre-release bundles may be found in GitHub releases page.

It may be less confusing for readers.

[TimMonko]

@TimMonko A general question. How would you feel about dev docs displaying the stable released bundle? Perhaps adding a comment that pre-release bundles may be found in GitHub releases page.

It may be less confusing for readers.

I switched it back to that, which is what Peter had implemented prior to my #958 .
There is, at L297 a reference to the releases page already :)
This should be ready to go now :)

[Czaki]

There is no 0.7.1 release yet.

Links should lead to 0.7.0 not 0.7.1

[TimMonko]

Woah thanks for looking at the build @Czaki , because locally I saw it correctly:

This did make me totally switch up the logic to what I think will work, but definitely need careful thought. I'll update PR description.

I also did add mention about pre-releases on the releases page on github, and not just earlier builds.

Edit:
CI Looks good

[Czaki]

Suggested change

	if napari_version.is_prerelease
	if napari_version.is_devrelease

napari==0.7.1a2 is prerelease, but not devrelease

[TimMonko]

I think with this current code we want 0.7.1a2 to point to 0.7.0, not the pre-release bundle (even though that was the original goal), so we want to use is_prerelease.

But you are right, if we do is_devrelease than I think 0.7.1a2 would point to the 0.7.1a2 bundle.

Can you confirm this logic?

[willingc]

@TimMonko I believe that if you want to use the stable version to avoid confusion for end users (i.e. dev docs version will always display the stable bundle) then we should be using bundle_version is stable_version = _stable_version_from_switcher().

[TimMonko]

@willingc can you check the logic I have in the description? #973 (comment)
A new stable release would not have the version_switcher updated, so if we did just that then it would be one version behind on each stable release.
But, admittedly, my brain is struggling to wrap up the logic

[Czaki]

You are right, the getting version from switcher will provide wrong version during deploy stable docs.

And there are two paths. User is opening napari.org/dev then we might want to provide stable release.

But when user enter napari.org/0.7.1 when 0.7.1 is not released yet, but have some alpha or beta then it should link to latest bundle, even alpha one.

[TimMonko]

We have decided in today's docs meeting that we want the dev docs to always point to the latest stable release, not alphas or rcs.

the blocker is stale, opinion still welcome