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 b38799e; 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]

Thanks for attention!

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.

Yes. I was aware of that, but forgot to update the list at some point. The old list worked for Ubuntu 22.04.

On the other hand, the new list may also be outdated at some point. That won't be a big problem because sage will install its own packages fetched from mirror sites for missing packages in the system. I added a remark in line 115-118.

[anneschilling]

For me --filter blob:none in the command
git clone -c core.symlinks=true --filter blob:none
--origin upstream --branch master https://github.com/sagemath/sage.git
did not work, so I left it out. Can it be omitted? If not, perhaps explain what it does.

[kwankyu]

--filter blob:none is supposed to "filter" unnecessary data so that cloning becomes fast. I don't know how it works.

I think it can be omitted. I never used it myself.

For me, -c core.symlinks=true is also not necessary. But it seems useful in Windows. So we should keep this.

[kwankyu]

Can it be omitted?

Done. Thanks.

[kwankyu]

Matthias, I fixed an error

diff --git a/src/doc/bootstrap b/src/doc/bootstrap
index e99ecd52c28..256ba085e0b 100755
--- a/src/doc/bootstrap
+++ b/src/doc/bootstrap
-        if [ -n "PKG_SYSTEM_PACKAGES" ]; then
+        if [ -n "$PKG_SYSTEM_PACKAGES" ]; then

Perhaps this error was not noticed before because PKG_SYSTEM_PACKAGES is always non-empty?

[tobiasdiez]

Awesome, this is a nice improvement! Thanks for the initiative.

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.

[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.