Move installation details from README to the installation guide

[kwankyu]

Currently we have two docs for installation: README.md and the Sage Installation Guide. There are severe problems:

• README is too complicated for a beginner to follow: too many details, jargons, too many branch points (links)
• There are many cross references between the README and the Guide. One has to hop between the two docs.

This PR aims to make README.md a light-weight easy-to-follow installation guide for newcomers and beginners trying to install Sage to their personal computers.

See the new README:

https://github.com/kwankyu/sage/tree/p/streamline-installation-guide#getting-started

The new README does not try to be comprehensive. That is the role of the Sage Installation Guide. Materials removed from README are incorporated to the Sage Installation Guide. The Sage Installation Guide would provide all the details for users for whom the README.md is not sufficient.

The installation guide in the README was tested with macOS, ubuntu, Windows WSL (ubuntu and fedora).

Along the way, I made extensive edits on the Sage Installation Guide. Most of them are non-technical.

See the new Sage Installation Guide:

https://doc-pr-38659--sagemath.netlify.app/html/en/installation/

In future, there would be little need to update the installation guide in README. Developers could focus only on updating the Sage Installation Guide as Sage evolves. This lessens maintenance burden.

📝 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 and checked the documentation preview.

⌛ Dependencies

[github-actions]

Documentation preview for this PR (built with commit 90bb8fa; changes) is ready! 🎉
This preview will update shortly after each push to this PR.

[egourgoulhon]

Thanks for this initiative to make the README lighter!

The Linux dependencies listed in the new README are outdated: the sage apt-get install ... command will generate errors in Ubuntu 24.04 LTS, as detailed in #38428.

Basically, one should suppress libbrial-dev, libbrial-groebner-dev, maxima-sage from the package list and replace libncurses5-dev by libncurses-dev.

A dependencies list that is known to work for Ubuntu 24.04 is posted at https://sagemanifolds.obspm.fr/install_ubuntu.html

[kwankyu]

I think one could even go a step further and extract all of the remaining install instructions in the readme to a "Install Quick Walkthrough" in the docs. So the readme just links to the docs. Similar to how its done in scipy/numpy.

That is not the aim of this PR. The aim is: README for quick walkthrough, installation guide for full details.

I think the quick walkthrough is short enough to put in README.

Most projects on github contain a simple installation guide in README.

[tobiasdiez]

I think one could even go a step further and extract all of the remaining install instructions in the readme to a "Install Quick Walkthrough" in the docs. So the readme just links to the docs. Similar to how its done in scipy/numpy.

That is not the aim of this PR. The aim is: README for quick walkthrough, installation guide for full details.

I think the quick walkthrough is short enough to put in README.

It's 6 screens long for me... what advantages do you see of having it in readme as opposed to the main documentation?

Most projects on github contain a simple installation guide in README.

If we would have a "simple" installation method, I wouldn't mind having a short 3-line cmd in the readme...

[kwankyu]

It's 6 screens long for me...

It would be still 6 screens long in the main documentation.

what advantages do you see of having it in readme as opposed to the main documentation?

The advantage is "having it in readme". I hope that a newcomer visiting our github repo have the impression that installing sage is not difficult. Our main installation guide is very long and complicated because it has all details explained. I think just looking at the installation guide makes one discouraged.

What is the advantage of moving it to the main documentation? Do you want readme to be one screen long? I don't.

[tobiasdiez]

It's 6 screens long for me...

It would be still 6 screens long in the main documentation.

what advantages do you see of having it in readme as opposed to the main documentation?

The advantage is "having it in readme". I hope that a newcomer visiting our github repo have the impression that installing sage is not difficult. Our main installation guide is very long and complicated because it has all details explained. I think just looking at the installation guide makes one discouraged.

Just to make this clear, my proposal was to move the info that is now in the readme to a new page in the docs. So that it as short/uncomplicated as in the readme.

What is the advantage of moving it to the main documentation?

Automatic checks of links, consistent page layout with other install-related pages, possibility to use advanced features such as tabs, possibility to use semi-dynamic info (such as the auto-generated linux install commands), ...

[kwankyu]

As stated in the PR description, the aim of this PR is to simplify the instruction guide in readme. README.md is a file directly accessible from the source tree while the installation guide is built from the source tree. I am not sure if removing completely the installation guide from README.md is desirable.

As I don't want to do that here, please create your own PR for that later.

[kwankyu]

Just to make this clear, my proposal was to move the info that is now in the readme to a new page in the docs. So that it as short/uncomplicated as in the readme.

Instead of having two versions in the main installation guide, I hope that the detailed guide is cleaned up and updated. It is now messy and will still be so after this PR.

[grhkm21]

can we bump this

[kwankyu]

OK. I will revise this soon.

[kwankyu]

To repeat, the main point of this PR is to make the README light, keeping the status quo of the traditional build procedures.

Making the README even lighter or changing build procedures departing from the status quo should go into new PRs after this one.

Please review.