Link to install tutorials from Astropy install docs

[eblur]

I wrote three tutorials on managing Astropy and Python versions using Anaconda environments.

The Learn Astropy team decided that these belong with the Astropy install docs.

[bsipocz]

I wonder how much it duplicates content already in the docs, whether duplicating pages is the right approach or the current ones need to be reworked?

The other thing is that any python2 content needs to be removed before it can be merged to core (e.g. the parts where setting up a python2 environment is shown). It's super useful content, but doesn't belong to the core package.

[eteq]

Hmm... I think @eblur is right that the Python 2 stuff is a useful thing for people to know - e.g. that they can use conda to set up a py2.x environment and get astropy that way. however I see @bsipocz's point that it's problematic to have a "how to install python 2.x" in a version that explicitly does not support python 2.x. So what about putting that tutorial over into the 2.0.x branch, and re-working this one to instead reference "an older version of astropy" instead of "python 2"? Then at this line in first tutorial we can link directly to the permanent location of the 2.0.x docs? That way users will see in perpetuity both how to recover a py 2.x environment and how to save their current astropy environment, but we don't give the impression that this specific version supports it.

In an out-of-band conversation with @eblur it was also pointed out that we should make it clear why this version isn't py 2-able, though (most importantly, that everyone upstream is dropping support at for py2 at the end of this year). Then hopefully fewer people will see this and come asking us why they can't have py2 in the newer versions. I couldn't find an obvious place where we say this in the docs, though. @bsipocz or @astrofrog, do you know of a place? (if not I can write something up perhaps as part of this PR)

[eteq]

Oh two other things in addition to the above

1. @bsipocz - can you clarify where you see duplication in the instructions? The only thing that's really obviously duplicating to me is the conda update astropy line in the current instructions, and I see this PR as providing more detailed than that rather than being actual duplication. So the base install page is the "short version" and these would serve as "for those who need a bit more hand-holding". But I agree if there's more overlap than I see in an initial read-through, a de-dupe pass is required.
2. @eblur - the doc build is failing - looks like there's some rst typos, like missing backticks or something?

[bsipocz]

1. @bsipocz - can you clarify where you see duplication in the instructions?

We already have instructions here of how to install the dev version and set up a dev environment. I see the point of having a more detailed, user facing version of it where the angle is pedagogical and more about to teach how to use conda environments, but that doesn't belong to the core library, and that's why it was in the tutorials originally.

And given the very short timescale of support left for LTS, I'm not sure I support any major revamp of the 2.0.x docs either to put in new python2 related stuff in there.

[eteq]

After some out-of-band discussion we (@eblur, @kelle, and I) are thinking the points @bsipocz brings up are signs that this is best done in something more like a astrobetter post, because the advice here might be better thought of as "time-stamped". That is, it's better to record a workflow that works now, but not put it here or in the tutorials so that it doesn't require maintenance.

So the idea would be to make such a post, but then link to the post from here (and on learn.astropy.org?), so that people who stumble on the install instructions see something more detailed than the rather terse content currently in the docs, while not having to worry about keeping it synced up with the install instructions already here. Sound reasonable?

That said, because the content is already here, at @eblur's request I'm leaving inline comments. But those are for the future post, not for inclusion as this PR itself.

[eteq]

Suggested change

	default.
	default. For more on the reasons for this, see the next tutorial.

[eteq]

Maybe add "Or run the downloaded file from the shell if you downloaded the command line version"?

[eteq]

Maybe add Astropy?:

Suggested change

	astronomers use frequently: *numpy*, *scipy*, and *matplotlib*
	astronomers use frequently: *numpy*, *scipy*, *matplotlib*, and *astropy*

I know below you're showing how it can be done in the astropy channel, which is still critical for affiliated packages. But maybe it's better to make the point here that astropy is in core anaconda too?

[eteq]

Maybe it's worth pointing out somewhere here that actually this part isn't necessary if you just use anaconda as provided, since the below packages are already in the base environment? Maybe just something like:

while these all come in anaconda by default, many other packages do not, and this illustrates the core functionality.

or similar?

[eteq]

To clarify here: the astropy channel is not actually maintained by anyone at STScI. the astropy channel is maintained by some of the Astropy team members basically as a volunteer effort. So maybe change to:

Suggested change

	*astropy* channel, maintained by AURA and STScI. To add this channel
	*astropy* channel, maintained by the Astropy Project. To add this channel

?

[eteq]

(if you go with my suggestion above about renaming the remote):

Suggested change

	git pull upstream master
	git pull astropy master

[eteq]

Again this might be overly pedantic... but technically the "git config file" is something different - this is actually adding the core Astropy repo as a "remote" in your local repo (whereas the git config file is shared across all repos on your computer)

[eteq]

(if you go with my suggestion above about renaming the remote):

Suggested change

	git push origin master
	git push <user-name> master

[eteq]

If someone has messed with their local master a lot (which I see from time to time) even --force doesn't work, and instead the thing to do is:

git fetch astropy
git reset --hard astropy/master

which is basically equivalent to completely deleting the local master and replacing it with the master on the "astropy" remote (or "upstream" if you decide not to go with my renaming suggestions)

[eteq]

This is probably the place to put the "why the py3 switch is happening", right @eblur? If so, here's some wording:

Note that when you have time you probably should try to port your code to Python 3.  Most of the Python scientific software ecosystem has moved from Python 2 to Python 3, because the Python core developers have not added new features to Python 2 since 2010, and are ceasing to support Python 2 entirely at the end of 2019.  This means things like security patches or compiler fixes will stop being issued for Python 2 at that time.  So Python 2 will become harder and harder to safely install after that.  Moreover, Python 3 is both more internally consistent and more feature-ful than Python 2.  For some discussion on how to convert scientific code to Python 3, see: https://python-3-for-scientists.readthedocs.io/en/latest/

Does that seem good?

[bsipocz]

After some out-of-band discussion we (@eblur, @kelle, and I) are thinking the points @bsipocz brings up are signs that this is best done in something more like a astrobetter post, because the advice here might be better thought of as "time-stamped". That is, it's better to record a workflow that works now, but not put it here or in the tutorials so that it doesn't require maintenance.

this is a super good idea, and in addition to what you listed above it may even reach more/different people than with the docs or tutorial notebooks.