DOC: Add complete install instructions

[ralphpeterson]

To avoid problems like #95.

[NickleDave]

We should add

• [ ] a separate installation page under getting started
  • [ ] with pip / conda tabs
  • [ ] and advice after like "use a virtualenv", "use a new virtualenv / conda env", "prefer conda in a conda env", etc
  • [ ] do we need any notes on dependencies? Not right now I think

[NickleDave]

@all-contributors please add @ralphpeterson for ideas userTesting

[allcontributors[bot]]

@NickleDave

I've put up a pull request to add @ralphpeterson! :tada:

[ralphpeterson]

i think general advice is good, but risks making the documentation too verbose. if you tell the user what to copy paste (what most self-taught coders doing bioacoustics research will probably want), then users will probably run into less issues. i think there's a balance to strike between educating and getting the package to work for people. perhaps a "best practices" section or something would be a good way to organize educational info without diluting the core info.

[NickleDave]

You are right, a link to a "good practices" section would help this avoid being verbose.

Not clear from what I wrote but "pip/conda tabs" will be the copy and paste commands, agree this is the key thing to have here

[ralphpeterson]

Sorry to split hairs on this, but I think that the quickstart should be even more explicit, assuming that your target audience includes novice python users. Of the beginners that I've taught python to, the top concept that confuses people is the idea of conda environments. Spelling out the install line by line could save some headaches in the future. I think a good example of this is keypoint-moseq.

With conda (preferred)

$ conda create --n vocalpy python=3.9 (<- insert python version vocalpy actually depends on)
$ conda activate vocalpy
$ conda install vocalpy -c conda-forge

With pip (use pip instead of conda if X happens)

$ conda create -n vocalpy python=3.9 (<- insert python version vocalpy actually depends on)
$ conda activate vocalpy
$ pip install vocalpy

[NickleDave]

Sorry to split hairs on this, but I think that the quickstart should be even more explicit, assuming that your target audience includes novice python users.

Spelling out the install line by line could save some headaches in the future.

You're not splitting hairs, you're right. We definitely want to be beginner friendly.
I actually started to write separate sections under what I added with step-by-step instructions but then thought better of it.

I re-opened this issue. In the next comment I'll write a to-do list on how I think we should fix.

Of the beginners that I've taught python to, the top concept that confuses people is the idea of conda environments.

The concept of environments is definitely confusing for beginners. It's even more confusing in Python, in part because there's more than one way to create an environment: e.g., with conda/mamba or with a pure Python tool like venv/virtualenv. For the case where you need to use a GPU, it's still much less painful to use conda. But for everything else, we are at a point where pure Python usually just works. And, without writing a diatribe here, it's not good for the Python community to be split into two. I wish there was "the one way" to do everything, but right now there's not, there's basically two, so I think we should show both.

So I prefer to have two sets of step-by-step instructions: one that shows using vanilla Python with the built-in venv tool, and one that shows using conda. As you said, we should be succinct, but I do think we should link to relevant resources, to help beginners, but not have those links interrupt the flow of text.

[NickleDave]

So @ralphpeterson what do you think about the following to close this?

• [ ] move the single-command version to the main index page, under an "Installation" heading. This should be where "getting started" is now (and the link to the quickstart tutorial is broken, I just realized)
• [ ] have a link there to "getting_started/installation", "for more detail see ..."
• [ ] have two sections "pure Python environment", "conda environment", each with step-by-step commands
• [ ] keep (maybe add) helpful links for beginners re:envs but also be succinct

Also would you want to take a stab at making these changes (assuming you agree)?

[ralphpeterson]

I think these are great changes. I can take care of the conda specific stuff, but don't use virtual envs all that often, so will need your help there.

[NickleDave]

Closed by #99