Add upgrade instructions for anaconda users - #1806

We should probably also add a note in docs/known_issues.rst, as this is a "bug" in an external package that we can't really deal with ourselves.

Agreed - this all looks good except that it should be a "Known issue".

In future, I think that anaconda and canopy are going to be very common installation paths for astropy, so it will make sense to mention them explicitly in the installation section too, not just known issues.

My suggestion for the 0.3 release would be to put something in both the installation instructions and in known issues. I don't think most users will think to look in known issues because following the installation instructions for ip will appear to have succeeded, and any code that happens to still be importing the bits of 0.2.5 that remain will continue to run as they did before the upgrade so user tests won't catch the problem either.

Both changes are now part of this pull request so you can add either or both.

I'm fine with the "both" solution too. In the future apparently Anaconda is working towards playing nicer with pip, so it might be that this will go away in future versions (there's an anaconda issue about this, but I can't find the link... @mwcraig sent it to me at one point). So at that point we might drop the instructions, but until then I see @astrofrog's point that it makes sense.

👍

There are now a ton of "Warnings" and "Notes" under the otherwise seemingly simple installation instructions using pip. It makes the whole thing look a lot more daunting than it should be. We can leave this as is for the purposes of this PR and for the 0.3 release. But I'd like to revisit this at some point.

If I understand from [1] how pip integration will work in conda, going forward the instructions for anaconda users will simply be to always use conda in place of pip. If conda install doesn't find a conda package for whatever is being installed it will invoke pip to do the install instead. This would be an improvement from the current situation, in which conda-installed packages show up in pip freeze even though they aren't actually managed.

The relevant excerpt from the continuum forum posting is:

Hello Ben,
the reason you are getting the message is because the new conda version has integration with pip. This means that when pip is installed, "conda list" will list pip installed packages in addition to conda packages. In addition, "conda install" will install packages using pip if no conda package is found.
Running:
$ conda install pip
will install the latest version of pip, such that this feature is enabled.

• Ilan

[1] https://groups.google.com/a/continuum.io/forum/#!topic/anaconda/JjFXwT0cSBg

Thanks, good to know.