Avoid duplicate / inconsistent environment descriptors

[brian-rose]

As discussed in #68 and #70, we currently have two different descriptions of the sphinx build environment:

• requirements.txt is used by pip
  • on readthedocs for automated testing of PRs
  • on GitHub Actions to build and deploy the actual portal site
• ci/environment.yml is used by conda, which we recommend for local building in our Contributor's Guide

We have no automated way to checking for inconsistencies between these two, which recently led to a local build error #68 . Clearly it's not ideal that our CI tests are not catching this.

A few paths forward:

1. Modify both GitHub Actions and readthedocs to use conda instead of pip, making sure they are building in a way that is consistent with our own local build instructions (my preference)
2. Change our Contributor's Guide to suggest using pip instead of conda (I don't think this is a good idea)
3. Find a CI tool that will automatically check for inconsistencies between the two environment files? (I don't know how to do this, but even if I did, it seems like a band-aid solution compared to 1.)

Thoughts from the Infrastructure team?

[ktyle]

I agree that we should use conda instead of pip whenever possible ... still run into situations where some packages don't exist on conda-forge, but can be found/installed via pip.

[dcamron]

Just want to hop in to mention that if we prefer/need to maintain one file compatible with both pip and conda (as long as we confirm every spec is available on both), you can conda create/install/update and conda env create/update with text specification files like requirements.txt, e.g. conda create -n <env> -c conda-forge --file requirements.txt. This is how @dopplershift has set up MetPy ci and contributors guide.

[dopplershift]

I'll also add that using requirements.txt with Conda has allowed us to pin versions of packages to avoid being broken by updates--instead we get to control when we move to new versions, rather than just potentially getting new versions whenever we do a new build. Instead we get PRs that update each version and let us see what the ramifications of the update are.

@ktyle If we have packages important for our ecosystem that are not yet available on conda-forge, I'm happy to help try to get them added.

[brian-rose]

@dopplershift is that specific to using requirements.txt? Can't you just as easily specify package versions in environment.yml?

[dopplershift]

If you want to use Dependabot to automatically issue Pull Requests to update the versions when new versions are released, then unfortunately only requirements.txt (and other such files) is supported right now (dependabot/dependabot-core#2227). On MetPy we decided eliminating random, unrelated PR builds failing was worth having the use of Conda with our dependency files being a bit more clunky.

[brian-rose]

I see, thanks!

Do we think this would be an asset for any of our Pythia repos? The dependencies are likely to get more complicated as the projects grow.

@andersy005 already submitted #72 that converts all our builds to conda. We could modify those to use requirements.txt rather than environment.yml