Update installation instructions for napari

[albevier]

Added Homebrew installation option for macOS users.

References and relevant issues

I recently had a PR for a homebrew cask to install napari accepted and merged.

Description

Specifies an option for macOS users who manage installed software with homebrew (cask).

Note: There is the appearance of two other edits, but I didn't change anything there. The only change is the addition at the end of the commit diff.

[Aniketsy]

@albevier Thanks for the PR 😊

[psobolewskiPhD]

Can you give a bit more context? what is being installed? is it our signed bundle app? or just the python package?

[albevier]

Can you give a bit more context? what is being installed? is it our signed bundle app? or just the python package?

It is the signed bundle from the github release page (same links that you have in the documentation). Homebrew cask automates the download, installation, and uninstallation of the program (as well as verifying the sha256 checksum).

[psobolewskiPhD]

Thanks, that helps a lot.
Is the bundle installer involved? will the user see the options and license info we have screenshotted in the current docs?

[albevier]

Thanks, that helps a lot. Is the bundle installer involved? will the user see the options and license info we have screenshotted in the current docs?

The bundle installer (*.pkg) is used, but via comand installation behind the scenes. The license agreement is never explicitly shown to the user, however I believe there is a way to inform users with a message via caveats.

[albevier]

In fact it would be simple to have a caveat for the EULA, for example:

caveats do
  license "https://github.com/napari/napari/blob/main/EULA.md"
end

[TimMonko]

Hi @albevier, welcome to our project! Thanks for doing something cool like adding this to cask, and especially for coming to open the changes in our docs :) That's probably the most helpful things!

In fact it would be simple to have a caveat for the EULA, for example:

caveats do
  license "https://github.com/napari/napari/blob/main/EULA.md"
end

Can you explain this more. Does this get added to the cask thing? The napari bundle itself? It's important to some institutions that their users only download code of certain licenses (of which the bundle should be normally ok)

Finally, since you are so responsive, could you add your note below the current text, so that users first see the "usual" instructions. And also, could you add it as a myst-style admonition? I don't mean to be picky, it's just helpful for guaranteeing our theme formatting works.
https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html

[albevier]

Hi @albevier, welcome to our project! Thanks for doing something cool like adding this to cask, and especially for coming to open the changes in our docs :) That's probably the most helpful things!

In fact it would be simple to have a caveat for the EULA, for example:

caveats do
  license "https://github.com/napari/napari/blob/main/EULA.md"
end

Can you explain this more. Does this get added to the cask thing? The napari bundle itself? It's important to some institutions that their users only download code of certain licenses (of which the bundle should be normally ok)

Finally, since you are so responsive, could you add your note below the current text, so that users first see the "usual" instructions. And also, could you add it as a myst-style admonition? I don't mean to be picky, it's just helpful for guaranteeing our theme formatting works. https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html

Hi, glad to be helping! I went ahead and made the change you requested related to position and format of the admonition (changed from note to tip). A homebrew cask is just a ruby script and this caveat is only added to that script to notify the user of any details they should be aware of when installing. It is not added to the napari package in any way, a cask just provides for managing the installation process in a more automated way for those users it suits (via the homebrew package manager). You can find the script for napari here.

[psobolewskiPhD]

Hmm, I'm not sure the new location of the info really makes sense.
This approach is like a easier/CLI alternative to clicking all the things in the screenshots -- if you have brew that is.

I just tested it, works great -- might really be the easiest & quickest way to get started with napari!
Brew is really awesome; i'm not sure i've ever installed a cask before but I use brew all the time for utilities and stuff -- i had my own R formula at one point when Apple Silicon first came out.

Brew is also supported on linux... 🤔

[psobolewskiPhD]

I think I would but the tip in this section, below the tiles?
https://napari.org/stable/getting_started/installation.html#install-as-an-application

It makes the most sense to me anyways, especially if at some point the brew install also works on linux.
The tiles take you to the manual download and GUI, the brew is a shortcut/alternative for those with brew.

[TimMonko]

Thanks for linking the cask script! That's pretty cool -- I'm quite naive on these thigns. Does this mean each napari release it will need to be updated, or is there automagic updates to the cask script for folks.

mm, I'm not sure the new location of the info really makes sense.
This approach is like a easier/CLI alternative to clicking all the things in the screenshots -- if you have brew that is.

@psobolewskiPhD Do you have any suggestions? Like do you think it still belongs on this bundle page or should it be moved to the "with Python" instructions since that's more CLI based. I'm not sure how used to these days folks are with one-liner CLI installs 🤔 I feel like its less common on Windows but probably more frequent on Unix systems so maybe does work as a "convencience" method compared to the bundle clicks

[Czaki]

hm. The problem that I see here is that on every update of napari via brew (just brew upgrade), the user will lose all his plugins and settings.

[albevier]

hm. The problem that I see here is that on every update of napari via brew (just brew upgrade), the user will lose all his plugins and settings.

This is an issue with the installer itself, not the homebrew cask. @TimMonko might be something to look into, although you already give a warning related to plugins and recommending the python installation.

As for @psobolewskiPhD's suggestion, I quite like it. Where the tip resides directly below the download links for the packages. I don't think it would make sense under the python section since it is really running the package installer and not installing via python (even if it is CLI based). As for Linux, yes! It would be as simple as editing the cask script to add the linux package.

[Czaki]

This is an issue with the installer itself, not the homebrew cask. @TimMonko might be something to look into, although you already give a warning related to plugins and recommending the python installation.

yes. And this is a reason why we do not provide any update mechanism at this moment. So the user needs to intentionally install the newer version.

User also can keep both versions at the same time and move this what he need by comapring. Where the brew mechanism will wipe all information from disk by removing the older version.

[brisvag]

If updating fully wipes without any warning about it, IMO we cannot merge this until we find a way around it, it's too much of a downside.

[albevier]

Ah I see, yes this is an issue then. There is a way in homebrew to pin the version so brew upgrade skips it. The user would invoke brew pin --cask napari. I'll add that line to the tip, but I can see the argument for not adding to official docs because of this.