Rework Install guide following on from #16555

[taldcroft]

Description

This pull request is to get the good work in #16555 across the finish line.
It starts from there and then makes significant changes to address some of the comments there. It also follows some of the ideas introduced in the developer documentation for making a dev environment. Most importantly:

• Rebase on main (Rewrite installation docs to not recommend anaconda / defaults channel #16555 has some bad conflicts).
• Front-load information about making a Python environment.
• Explicitly recommend against using miniconda or Anaconda based environments.
• Document installing astropy using pip. Using conda (i.e. conda install astropy) is mentioned only in passing.
• Overall simplify the flow and language where possible.

Close #16555

• By checking this box, the PR author has requested that maintainers do NOT use the "Squash and Merge" button. Maintainers should respect this when possible; however, the final decision is at the discretion of the maintainer that merges the PR.

[github-actions]

Thank you for your contribution to Astropy! 🌌 This checklist is meant to remind the package maintainers who will review this pull request of some common things to look for.

• Do the proposed changes actually accomplish desired goals?
• Do the proposed changes follow the Astropy coding guidelines?
• Are tests added/updated as required? If so, do they follow the Astropy testing guidelines?
• Are docs added/updated as required? If so, do they follow the Astropy documentation guidelines?
• Is rebase and/or squash necessary? If so, please provide the author with appropriate instructions. Also see instructions for rebase and squash.
• Did the CI pass? If no, are the failures related? If you need to run daily and weekly cron jobs as part of the PR, please apply the "Extra CI" label. Codestyle issues can be fixed by the bot.
• Is a change log needed? If yes, did the change log check pass? If no, add the "no-changelog-entry-needed" label. If this is a manual backport, use the "skip-changelog-checks" label unless special changelog handling is necessary.
• Is this a big PR that makes a "What's new?" entry worthwhile and if so, is (1) a "what's new" entry included in this PR and (2) the "whatsnew-needed" label applied?
• At the time of adding the milestone, if the milestone set requires a backport to release branch(es), apply the appropriate "backport-X.Y.x" label(s) before merge.

[pllim]

So this supersedes #16555 ?

[taldcroft]

So this supersedes #16555 ?

That's the plan.

[neutrinoceros]

It may have been discussed previously but I don't think I get the flow we're going for here: are we encouraging users to use conda and pip to install astropy ? This seems like a recipe for disaster. In fact, I happen to have a screenshot from an older version of astropy's documentation that explicitly warned against it

[taldcroft]

The plan is to create a vanilla conda environment with only Python and about a dozen other core packages that come along for the ride. After that, use pip for everything. I think this is quite safe.

What might cause issues is installing astropy from conda and then upgrading with pip, or vice versa. But it's worth mentioning that I think conda has gotten better with this mixed-method installation, at least in my experience. I regularly pip-install packages over a conda version and haven't had any problems recently. That doesn't mean it can't happen, but it hasn't happened to me in the last ~5 years.

[taldcroft]

This strategy is basically what's in the developer docs. Going all-in with pip once the environment is created should minimize issues.

[neutrinoceros]

The plan is to create a vanilla conda environment with only Python and about a dozen other core packages that come along for the ride. After that, use pip for everything. I think this is quite safe.

In my experience people tend to follow instructions for environment creation and stick with those envs, so I'm not sure it's safe to assume that the only evolution that their env will see is what our instructions guide them through.
But in general I don't think conda solves any of my problems, hence I'm not comfortable with recommending anything other than pip (and maybe uv these days but I wouldn't through that one at a beginner yet). In short: I'm not sure I can help with this conversation.

[taldcroft]

But in general I don't think conda solves any of my problems

Conda has solved these problems for me:

• Installing any version of Python on Mac (or any of our supported platforms) in a lightweight and easily reversible way.
• Easily installing graphviz on Mac to allow building the docs.
• Installing Python on Windows and providing a capable shell that allows using that Python from a terminal.

[neutrinoceros]

This is just ugly and prone to breakage.

I would say "explicit and robust" 😄
(but it does add some maintenance burden)

[Cadair]

Well I think that's a bug with the conda recipe, see conda-forge/astropy-feedstock#137 which was the minimal suggestion. Given the lack of optional dependencies in conda the general approach is to list all optional dependencies, which I am not sure why this isn't the case.

[astrofrog]

I thinking we did discuss, maybe at the coordination meeting, that the conda recipe should be updated to include all optional dependencies. People who would want minimal installs are unlikely to be using conda.

[mhvk]

Is there a better way?

Use linux 😺? (sorry, couldn't resist, but, really, it is sad how the lessons they learned from package management have been ignored by the python ecosystem)

More to the point, most users I've seen behave like those @neutrinoceros described, create an environment and stick with it, so the example of @Cadair of a later conda install is indeed worrying. But that perhaps also means that giving the very long conda install comman is not such a big deal.

I guess my suggestion would be for the conda baseline to be just that, and then use that long line as a reason to describe the pip install as an alternative, one that is perhaps especially good if one's system python is actually recent.

[Cadair]

astropy/astropy-APEs#86 (comment)

[mhvk]

I like the idea of going towards installing just with pip, as it is right now the "standard" way. I'm also fine with suggesting mini-conda, but not sure why we're essentially repeating the information that is already at https://github.com/conda-forge/miniforge -- I think it might be better to just point people to that and let them follow the instructions there. That then also avoids problems with the links to the various downloads getting out of date.

[taldcroft]

I think it might be better to just point people to that and let them follow the instructions there.

Looking at the miniforge instructions today, they seem good enough. @Cadair didn't agree, but since this issue about repeating the instructions has been such a sticking point in review, I'm just going to remove them.

[pllim]

General comment that might apply in multiple places here: Doc :ref: label should not be changed if you can help it, because it might break downstream intersphinx linking.

Still not a fan of us hosting miniforge installation doc (what if something is horribly broken and cause us to do a release to just fix the doc?) but given the urgency stated at CoCo tag-up today and in other discussions, I am okay with this as long as we have a follow-up issue to move this doc somewhere else like OpenAstronomy or Learn Astropy, knowing and accepting the risk that anyone who links to the install doc here would have broken links when that happens.

[taldcroft]

Still not a fan of us hosting miniforge installation doc

Removed!

[taldcroft]

I think I have addressed the big-picture review comments, but I may have missed something.

@pllim - about the :ref: names, I didn't get a chance to scrub for changes. I don't recall renaming any of them for no reason, but with the re-organization I know that some just didn't have a place any more.

[pllim]

some just didn't have a place any more

I guess if people start complaining of broken link, we can put a dummy section back or something. Thanks for the clarification!

Removed!

I was told to state my thoughts but I was also told that some prefers the installation here and only wants it moved later (not this PR). 😬 cc @eteq

[pllim]

LGTM now FWIW. Thanks!

[taldcroft]

@pllim - about removing the install instructions, I had decided to do that earlier after having another look at the native miniforge README instructions, also prompted by #16987 (review).

[mhvk]

I think this is a huge improvement. I'm hoping we'll soon be able to simplify the conda one with the introduction of an astropy and astropy-base/minimal/whatever one, but don't think we should wait for that. Thanks, @taldcroft!

[pllim]

Let's do it then. If people feel strongly about removal of the install miniforge stuff, probably better as follow up PR. Thanks, all!

[pllim]

Aww man, I think the dev docs reorg made auto backport impossible.

@taldcroft , are you interested in manual backport?

Everyone, let's wrap up astropy/astropy.github.com#617 next.

Thanks!

[taldcroft]

@pllim - about the manual backport, actually resolving the conflict is a mess and not tenable (at least by me). However, I have a branch set up that simply copies docs/install.rst from upstream/main to the backport PR. That seems to build OK locally except an unrelated WARNING: autosummary: stub file not found 'astropy.units.function.logarithmic.m_bol'. Check your autosummary_generate setting.

Does that sound like a plan?

[pllim]

@taldcroft , I think that is acceptable. I don't think install has changed that dramatically between your re-org (though the diff would tell us for sure).

You can ignore logarithmic.m_bol warning. That always happens on OSX and Windows because they are case-insensitive.

Thanks!

[taldcroft]

@pliim - see #17039 to see if I managed to get it right!

[pllim]

For completeness, we just merged astropy/astropy.github.com#617 as well.