Move installation details from README to the installation guide #38659

kwankyu · 2024-09-14T05:00:53Z

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

#38676 to fix ci for doc preview

github-actions · 2024-09-19T05:02:45Z

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

egourgoulhon · 2024-09-22T09:21:57Z

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 · 2024-09-27T05:01:19Z

--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 · 2024-09-27T05:11:01Z

Can it be omitted?

Done. Thanks.

README.md

Co-authored-by: Matthias Köppe <[email protected]>

kwankyu · 2024-09-28T00:12:25Z

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.

tobiasdiez · 2024-09-28T02:29:56Z

src/doc/en/installation/index.rst

-      :ref:`sec-installation-from-sources`.
+- Alternatively, follow the instructions in section
+  :ref:`sec-installation-conda-develop`;
+  these describe an experimental method that gets all required


Conda is not experimental since a very long time.

Given the many (recent?) problems with installing various packages in sage-the-distro, conda should actually be mentioned first, and only then the installation from source. Would safe us a lot of headache.

I don't agree. Traditionally building from source is the main way of installing sage for developers.

But perhaps this may be debatable in sage-devel. If there is a consensus in favor of conda, then we may change this part later. But this is for another PR.

Not in scope of this PR.

Making conda the default has been already discussed on the mailing list with only positive feedback (by people other than me): https://groups.google.com/g/sage-devel/c/AvH3xq2bCfo/m/OKwqzrrYCwAJ

In either way, this mode of installation is definitely not "experimental".

OK, I removed "experimental".

I don't mind whether conda is the default or not. I just don't want to make the changes here myself because I don't have much experience with conda and I am not sure if the change is desirable.

I would be happy if you make a followup PR just for the change.

tobiasdiez · 2024-09-28T02:32:23Z

src/doc/en/installation/index.rst

-  - No development: **Do you have root access (sudo)?**
+- **I have root access (can use sudo command):** Then the easiest way to install Sage is
+  through a Linux distribution that provides it as a package.  Some
+  Linux distributions have up-to-date versions of Sage,


I think this can be improved. Instead of sending people to repology, just name the very few distros (arch, gentoo) that actually have an up-to date version of sage. And given that this is not the case for the bigger players like ubuntu, I would put the conda install first again (as it will apply to most people).

Sending people to repology seems better because it would have up to date information. If we hard-code them, it would be easily out of date.

I added

You may need to consider upgrading your Linux distribution because a recent version of Sage is only available on a newer version of the distribution. + If there is no up-to-date version for your Linux distribution, you may + consider `conda`, as explained below. +

instead of recommending conda first.

Sending people to repology seems better because it would have up to date information. If we hard-code them, it would be easily out of date.

Maybe do both? If you are on Gentoo or Arch Linux (or [any other distribution that provides an up-to-date Sage package](<link to repology>), then use your system package manager to install Sage. Otherwise .... This is definitely more user-friendly, which should be the major aim of these instructions.

How can we be sure that Gentoo and Arch Linux will provide an up-to-date sage? Is Gentoo providing an up-to-date sage now? It is not in the current repology list.

How can we be sure that Gentoo and Arch Linux will provide an up-to-date sage?

If it's outdated, we need to update the recommendation. Same as for https://doc.sagemath.org/html/en/installation/linux.html.

As said in the PR description, one of the goals is to make the instructions in the readme as stable as possible so that we could only focus on the main installation guide as update occasions arise.

kwankyu · 2024-09-28T04:08:58Z

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 · 2024-09-28T05:19:41Z

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 · 2024-09-28T09:18:15Z

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 · 2024-09-30T05:50:34Z

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 · 2024-09-30T06:23:19Z

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 · 2024-09-30T06:48:32Z

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.

kwankyu changed the title ~~Take out gory installation details from README.md and put them in Installation guide~~ Move installation details from README.md to the Installation guide Sep 14, 2024

kwankyu changed the title ~~Move installation details from README.md to the Installation guide~~ Move installation details from README.md to the installation guide Sep 14, 2024

kwankyu added the c: documentation label Sep 14, 2024

kwankyu changed the title ~~Move installation details from README.md to the installation guide~~ Move installation details from README to the installation guide Sep 14, 2024

kwankyu force-pushed the p/streamline-installation-guide branch 9 times, most recently from 0463362 to e55a675 Compare September 14, 2024 13:34

Make README.md slim

ccd9dca

kwankyu force-pushed the p/streamline-installation-guide branch from f3ea24e to ccd9dca Compare September 20, 2024 04:56

kwankyu marked this pull request as ready for review September 21, 2024 00:07

kwankyu added the s: needs review label Sep 21, 2024

kwankyu force-pushed the p/streamline-installation-guide branch from b568039 to 4d0311d Compare September 21, 2024 00:40

Edits on README

285a6ad

kwankyu force-pushed the p/streamline-installation-guide branch from 4d0311d to 285a6ad Compare September 21, 2024 00:46

Remove parentheses in title

e49e076

kwankyu requested a review from mkoeppe September 21, 2024 00:54

Fix a typo

a5d5510

egourgoulhon added s: needs work and removed s: needs review labels Sep 22, 2024

saraedum mentioned this pull request Sep 22, 2024

Automatically build flatsurf installer flatsurf/sage-flatsurf#248

Merged

5 tasks

kwankyu added 2 commits September 22, 2024 20:46

Merge branch 'develop' into p/38659/streamline-installation-guide

935bf2b

Update package list for ubuntu

a67fe30

Edits of troubleshooting

dbc01bf

kwankyu added 2 commits September 27, 2024 14:04

Remove --filter blob:none

0bb13a3

also in the installation guide

019185d

mkoeppe reviewed Sep 27, 2024

View reviewed changes

README.md Outdated Show resolved Hide resolved

mkoeppe reviewed Sep 27, 2024

View reviewed changes

README.md Outdated Show resolved Hide resolved

kwankyu and others added 3 commits September 28, 2024 06:45

Panic is a verb not an adjective

cb3741d

Co-authored-by: Matthias Köppe <[email protected]>

Remove hardcoded list

d42c0fc

Small edit

2330642

Remove spaces before prompt

1b61eeb

tobiasdiez suggested changes Sep 28, 2024

View reviewed changes

Recommend conda for no up-to-date packages

d4ba6a9

Remove experimental

83ee30f

kwankyu added 2 commits September 30, 2024 14:51

Small edit

4bd7379

Merge branch 'develop' into p/38659/streamline-installation-guide

b8499f0

kwankyu force-pushed the p/streamline-installation-guide branch from 74471bc to b8499f0 Compare September 30, 2024 05:52

kwankyu added 6 commits October 8, 2024 13:17

Fix a typo

36aef3a

Fix a typo

6318199

Support line continuation for easy copy

02576d6

Merge branch 'develop' into p/38659/streamline-installation-guide

4599353

Merge branch 'develop' into p/38659/p/streamline-installation-guide

65f3178

Remove duplicate entry

f04ce3f

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Move installation details from README to the installation guide #38659

Move installation details from README to the installation guide #38659

kwankyu commented Sep 14, 2024 •

edited

Loading

github-actions bot commented Sep 19, 2024 •

edited

Loading

egourgoulhon commented Sep 22, 2024

kwankyu commented Sep 27, 2024

kwankyu commented Sep 27, 2024

kwankyu commented Sep 28, 2024

tobiasdiez left a comment

tobiasdiez Sep 28, 2024

kwankyu Sep 28, 2024

tobiasdiez Sep 28, 2024

kwankyu Sep 28, 2024

tobiasdiez Sep 28, 2024

kwankyu Sep 28, 2024

tobiasdiez Sep 28, 2024

kwankyu Sep 28, 2024

tobiasdiez Sep 30, 2024

kwankyu Sep 30, 2024

kwankyu commented Sep 28, 2024

tobiasdiez commented Sep 28, 2024

kwankyu commented Sep 28, 2024

tobiasdiez commented Sep 30, 2024

kwankyu commented Sep 30, 2024

kwankyu commented Sep 30, 2024 •

edited

Loading

Move installation details from README to the installation guide #38659

Are you sure you want to change the base?

Move installation details from README to the installation guide #38659

Conversation

kwankyu commented Sep 14, 2024 • edited Loading

📝 Checklist

⌛ Dependencies

github-actions bot commented Sep 19, 2024 • edited Loading

egourgoulhon commented Sep 22, 2024

kwankyu commented Sep 27, 2024

kwankyu commented Sep 27, 2024

kwankyu commented Sep 28, 2024

tobiasdiez left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwankyu commented Sep 28, 2024

tobiasdiez commented Sep 28, 2024

kwankyu commented Sep 28, 2024

tobiasdiez commented Sep 30, 2024

kwankyu commented Sep 30, 2024

kwankyu commented Sep 30, 2024 • edited Loading

kwankyu commented Sep 14, 2024 •

edited

Loading

github-actions bot commented Sep 19, 2024 •

edited

Loading

kwankyu commented Sep 30, 2024 •

edited

Loading