Update Conda installation instructions to use Miniforge

[tobiasdiez]

Based on the discussion in https://groups.google.com/g/sage-devel/c/GaQHdu0Q6UU and #37184, we now follow the offical recommendation and use Miniforge over the soft-deprecated Mambaforge. Since we are exclusively testing on miniforge, this change also aligns the docs with the ci.

Moreover, I've removed the recommendation to install mamba (using conda install mamba) which is not recommended according to the offical docs.

📝 Checklist

• The title is concise and informative.
• The description explains in detail what this PR is about.
• I have linked a relevant issue or discussion.
• I have created tests covering the changes.
• I have updated the documentation accordingly.

⌛ Dependencies

[williamstein]

This looks good to me and nicely aligns with upstream recommendations. Also, as mentioned on sage-devel, I personally found that the new recommended "miniforge" approach works very well for installing the correct version of sage. I also did further testing installing tensorflow and pytorch into the same environment, and all worked well together.

[williamstein]

I wrote my positive review in a comment on the PR.

[github-actions]

Documentation preview for this PR (built with commit 40de356; changes) is ready! 🎉

[kcrisman]

Thanks for checking this all works on Linux, @williamstein Do you (or someone at SMI) have access to a Windows machine they can test the equivalent of #37184 for Windows on? Then either a change based on that ticket could be a second commit here, or another PR.

[roed314]

Looks good.

[tobiasdiez]

@kcrisman Sorry for the confusion caused over at #37534 and #37184. For the background: Matthias blocked me and other members of the sage community on github. This means that I cannot post on his PRs (changing the label is the only way I can interact with them). I've asked the sage-abuse team to please forward my reviewer comments. As when playing Chinese whispers (or telephone in the US?), the main message got lost and reduced to a "-1".

So let's try again:

For #37184: Replacing mambaforge was one of the points (which now fortunately has been fixed). The main criticism I have, however, is that large parts of the documentation are now copy & paste. This makes it harder to maintain them in the future as they are prone to diverge over time. My suggestion is to instead use https://docutils.sourceforge.io/docs/ref/rst/directives.html#replace to reuse text without duplication (or perhaps extract it to a new file and include it twice).

For #37534: -1 on recommending devcontainers as a means for using sage in such a prominent place. I actually tried this setup for some time but it's quite cumbersome. I can see it working for someone that uses vscode for all sage work and who has all documents in one directory. But it's not suitable for most people based on my experience. The installation instructions should give a clear path that is suitable for most users, and not be a labyrinth of 50 different installation options. I suggest to put this addition in a completely new section/document (perhaps "Using SageMath via Developer Containers") and then link to that section in the "Installation instructions" as a possible alternative. The whole devcontainer setup is also an option for linux and macos users (with the same limitations).

[tobiasdiez]

Thanks everyone for the review!

[kcrisman]

@kcrisman the main message got lost and reduced to a "-1".

Thanks, and in the meantime I've been brought a bit up to speed.

For #37184: Replacing mambaforge was one of the points (which now fortunately has been fixed). The main criticism I have, however, is that large parts of the documentation are now copy & paste.

To be sure. Obviously fixing that would be part of a much larger effort, presumably there are multiple such places. (I presume we haven't used that directive before in our doc, yet, which may be an old assumption.)

For #37534: -1 on recommending devcontainers as a means for using sage in such a prominent place. I suggest to put this addition in a completely new section/document

That's my gut feeling as well, but I have to test it out first.

[tobiasdiez]

For #37184: Replacing mambaforge was one of the points (which now fortunately has been fixed). The main criticism I have, however, is that large parts of the documentation are now copy & paste.

To be sure. Obviously fixing that would be part of a much larger effort, presumably there are multiple such places. (I presume we haven't used that directive before in our doc, yet, which may be an old assumption.)

Of course, I only mean that there should be no new duplication introduced in the PR (not that all existing duplications should be fixed). The WSL setup instructions are added twice, and the instructions on how to setup the conda environment is essentially also a copy & paste of the instructions in the conda section.

[kcrisman]

Of course, I only mean that there should be no new duplication introduced in the PR (not that all existing duplications should be fixed). The WSL setup instructions are added twice, and the instructions on how to setup the conda environment is essentially also a copy & paste of the instructions in the conda section.

I see. I guess I understand the sentiment, but don't feel that this documentation upgrade is the place to introduce a change of this type. We (meaning Sage) have often teetered pretty close to the edge of letting the perfect be the enemy of the good (or acceptable, or something). A good compromise would be to immediately start a new PR that introduces this new (to Sage, I guess) syntax, with this and perhaps one or two other well-chosen exemplars as test cases. Then a lot of people can try out building doc with that. I would seriously hesitate to improve the "forge" doc in this way on its own, though. The bleeding edge can bleed you out, to make a dubious metaphor. And of course another good option would be to start by changing the developer guide to have some proscription on introducing new duplications, with lots of advertising on Sage-devel (though how would one enforce it... ) Anyway, a discussion for another time, and probably for others than me, since I haven't written much doc lately (and that which I did surely has many duplications!).

[tobiasdiez]

a new PR that introduces this new (to Sage, I guess) syntax, with this and perhaps one or two other well-chosen exemplars as test cases.

We already use include in about 80 places in the docs, and rst substitutions are also already used in a couple of places (mostly for images though). Both features are also pretty standard. Personally, I find the DRY principle one of the most important aspects to have a maintainable project (including docs).

And of course another good option would be to start by changing the
developer guide to have some proscription on introducing new duplications,
with lots of advertising on Sage-devel

This sounds like a very good idea!