Update how-to-use document to provide information on conda env setup

[clyne]

This PR partially addressed #127; it updates the how-to-use document to address conda environment setup.

[github-actions]

This pull request is being automatically built with GitHub Actions and Netlify. To see the status of your deployment, click below.

🔍 Git commit SHA: 1cd9df7
✅ Deployment Preview URL: https://61c2962041a71fe5ab2c6d88--pythia-foundations.netlify.app

[brian-rose]

Thanks @clyne, I had a PR in the works for this (addressing #198) but you beat me to it.

This looks great except that the name of the environment is incorrect. You need to do

conda activate pythia-book-dev

not pythia-foundations.

Unless we are changing the name of our conda environment! Which might be a good idea.

[clyne]

Thanks @clyne, I had a PR in the works for this (addressing #198) but you beat me to it.

This looks great except that the name of the environment is incorrect. You need to do

conda activate pythia-book-dev

not pythia-foundations.

Unless we are changing the name of our conda environment! Which might be a good idea.

Whoops. Good catch. Thanks. Fixed!

[brian-rose]

Hmm there are still several references to "activate pythia-foundations" in the text.

Should probably change to "activate pythia-book-dev"

[clyne]

Hmm there are still several references to "activate pythia-foundations" in the text.

Should probably change to "activate pythia-book-dev"

Indeed. Apparently the search function inside GitHub "file edit" doesn't work as I expected. I'm reasonably confident I've gotten them all now :-). Thanks for catching that twice!

[brian-rose]

Thanks @clyne, I don't see any more problems.

I do have one little suggestion. We could add a sentence like this:

"If you prefer to create your own minimal conda environment for an individual notebook, in most cases you can just look at the import statements to see which Python packages are required."

[clyne]

The "How to use this" book section is the first thing students will see when visiting the Pythia Foundations site. It assumes that they are novices and know nothing about Python environments, conda, etc. I'm afraid that telling a novice that they can figure out dependencies by inspection won't be very helpful if they don't know how to resolve the dependencies. Also, this setup method isn't foolproof; there can be issues with software versioning. Thoughts?

[brian-rose]

All true! I'm not suggesting that we provide detailed support for this "roll your own" approach. There is no need because we are already offering an easy option for beginners that "just works" (using our environment.yml file).

My comment is more meant for the adventurous type who wants to understand a little bit about how environments work, and their relationship with python code. Particularly if they are trying to adapt one of notebooks for their own application using just a few packages.

For example, I can imagine myself as a newcomer to python first following the instructions to create the all-inclusive environment, seeing that it works, but also seeing that it installed a very long list of stuff and wondering how much of that is really necessary.

Anyway I don't have strong feelings about it and not insisting on it. The adventurous type will usually figure these things out on their own.