Docs page - how to install python/conda/napari from scratch

[GenevieveBuckley]

We need a documentation page explaining how to install python/conda/napari from scratch (also jupyter notebooks?)

Good links:

• The Anaconda distribution
  of python is recommended.
• Managing conda environments
• Try Jupyter

[GenevieveBuckley]

This would likely go in the "absolute beginners" section (for people who are new to python) of @melissawm's docs reorganization napari/napari.github.io#176

[chili-chiu]

see also issue #46

[melissawm]

I am wondering if the links in the current installation page are enough?

Instead of writing a new guide which needs to be maintained, I would favor linking out to some resource such as the official conda installation page.

[alisterburt]

totally agree @melissawm ! Would be great if this was better.

The conda instructions are great but not super friendly - if the goal is to make the guide 'a friendly introduction' maybe something like @jni's https://jni.github.io/using-python-for-science/intro-to-environments.html should be added too!

Could be divided over two sections:

I'm new to all this... 😨

jni-like friendly thing

I'm a Python pro! 🐍

conda instructions

[psobolewskiPhD]

I posted this in another issue but can't find it.
I would vote for a top level Installation page (where we have Usage, Plugins, Community)
that is dedicated to Installation. Having install stuff be under Usage is counter intuitive to me.
I would second linking to other vetted resources, rather than duplicating work, but a short summary of the options and caveats is a good idea.
So starting with this page:
https://napari.org/stable/tutorials/fundamentals/installation.html
but with a bit more resources.

[melissawm]

How do we feel about this page as it is now on latest? Personally I think it's pretty complete, and more information may be too much.

[GenevieveBuckley]

How do we feel about this page as it is now on latest? Personally I think it's pretty complete, and more information may be too much.

I think the problem with that page is it starts by assuming you already have python & conda already set up. I think the page is ok after that, it's the very first part about pre-requisites where a lot of people will get lost.

This issue is specifically about how to install python and conda from scratch, as well as napari. It currently doesn't do a good job with the first two.

Here's what the page says about per-requisites right now:

It requires:

• Python 3.8–3.10
• the ability to install python packages via pip OR conda-forge

You may also want:

• an environment manager like conda or venv (Highly recommended)

Things I don't like about this section:

• There's no information about how to check if your system has python already, if you don't already know whether you have it or not.
• The link for python takes you to https://www.python.org/downloads/ Is this really how we prefer people to install python? I would suggest that very few of the core developers and regular users have installed their python this way, which seems like a potential problem. I think it's more common for people to have Anaconda/miniconda/mambaforge/etc. Because there's so many ways to do things, I think it's hard to pick one best/easiest way
• The link for pip takes you to a page on PyPI that says "pip install pip". This is unhelpful for a user who needs to answer the questions "How do I know if I already have pip installed or not?" and then "Ok, how do I install pip, then?".
• The link for conda also takes you to a page that says a lot about how you can install other packages using conda, but nothing about how to install conda itself. Again, at this stage what users really need to know is how to install conda.
• The second section of bullet points is titled "you may also want" but then has in parenthesis "highly recommended", which seems contradictory. If it's highly recommended, put that in the title.

What I would like to have here:

• instructions for the user about how to tell if they already have python or not, and pip, and conda.
• a very prescriptive, step by step set of instructions that will take you through the easiest and most dependable way to get set up.
• how to check if the installation(s) have gone correctly or not. Adding info on how to check after each step if things are working correctly would be ideal.

You're right that more information on the "How to install napari" page might be too much, and this is a lot of info so I'm imagining we'll need to put it in a "Install pre-requisites" page and link to it from the "How to install napari" page.

[jni]

I agree that all of the above things are useful @GenevieveBuckley but I don't think that they belong in the napari docs. Otherwise, all of napari, numpy, scipy, matplotlib, scikit-image, etc. each would need to have this exact same information.

imho, this kind of information belongs in (for example) scientific-python.org, after which we can point people to it.

The one caveat to all of the above is that sometimes it's useful to have the motivation of wanting to learn napari driving someone to learn Python. In that scenario, it might be useful to have a targeted tutorial like "learn Python with napari". But I don't think that that is the same thing that you mentioned — that still belongs in a more generic web page. Again, imho.

[GenevieveBuckley]

I agree that all of the above things are useful @GenevieveBuckley but I don't think that they belong in the napari docs.

I mean, I'm happy if we link to that. Right now the links are not necessarily even about how to install those pre-requisites.

[psobolewskiPhD]

What if in the https://napari.org/dev/tutorials/fundamentals/installation.html#install-as-python-package-recommended section we say something like:

New to Python or not familiar with virtual environments? You can use our Bundled App to get started or first look at some resources we recommend.

And that could link to a simple ordered list of resources related to getting started with conda and venvs.
e.g.
Scientific Python: Getting started with Python for science
https://lectures.scientific-python.org/intro/index.html

Talley Lambert: Python environments workshop
https://hackmd.io/@talley/SJB_lObBi

We could even mention for those interested in contributing the
Carpentries GIT workshop:
https://swcarpentry.github.io/git-novice/