gh-37261: `README.md`: Improve PyPI install instructions
    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->

Based on https://groups.google.com/g/sage-devel/c/1viBzw-
ZaoQ/m/ZBbjHXGEAAAJ, we improve the section on installation from PyPI.

We also improve **sage_conf** so that `python3 -m sage_conf` is
equivalent to `sage-config`.
After the next stable release is out, we can use this to simplify these
installation instructions.

Blocker because we need this to go in the 10.3 stable release.

<!-- Why is this change required? What problem does it solve? -->
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes #12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [x] The title is concise, informative, and self-explanatory.
- [x] 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

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #37261
Reported by: Matthias Köppe
Reviewer(s):

Author: Release Manager

README.md

@@ -420,16 +420,47 @@ in the Installation Guide.
 Alternative Installation using PyPI
 ---------------
 
-For installation of `sage` in python using `pip` you need to install `sagemath-standard`. First, activate your python virtual environment and follow these steps:
+For installing Sage in a Python environment from PyPI, Sage provides the
+`pip`-installable package [sagemath-standard](https://pypi.org/project/sagemath-standard/).
 
-            $ python3 -m pip install sage_conf
-            $ ls $(sage-config SAGE_SPKG_WHEELS)
-            $ python3 -m pip install $(sage-config SAGE_SPKG_WHEELS)/*.whl sage_setup
-            $ python3 -m pip install --no-build-isolation sagemath-standard
+Unless you need to install Sage into a specific existing environment, we recommend
+to create and activate a fresh virtual environment, for example `~/sage-venv/`:
 
-You need to install `sage_conf`, a wheelhouse of various python packages. You can list the wheels using `ls $(sage-config SAGE_SPKG_WHEELS)`. After manual installation of these wheels, you can install the sage library, `sagemath-standard`.
+            $ python3 -m venv ~/sage-venv
+            $ source ~/sage-venv/bin/activate
 
-**NOTE:** You can find `sage` and `sagemath` pip packages but with these packages, you will encounter `ModuleNotFoundError`.
+As the first installation step, install [sage_conf](https://pypi.org/project/sage-conf/),
+which builds various prerequisite packages in a subdirectory of `~/.sage/`:
+
+            (sage-venv) $ python3 -m pip install -v sage_conf
+
+After a successful installation, a wheelhouse provides various Python packages.
+You can list the wheels using the command:
+
+            (sage-venv) $ ls $(sage-config SAGE_SPKG_WHEELS)
+
+If this gives an error saying that `sage-config` is not found, check any messages
+that the `pip install` command may have printed. You may need to adjust your `PATH`,
+for example by:
+
+            $ export PATH="$(python3 -c 'import sysconfig; print(sysconfig.get_path("scripts", "posix_user"))'):$PATH"
+
+Now install the packages from the wheelhouse and the [sage_setup](https://pypi.org/project/sage-conf/)
+package, and finally install the Sage library:
+
+            (sage-venv) $ python3 -m pip install $(sage-config SAGE_SPKG_WHEELS)/*.whl sage_setup
+            (sage-venv) $ python3 -m pip install --no-build-isolation -v sagemath-standard
+
+The above instructions install the latest stable release of Sage.
+To install the latest development version instead, add the switch `--pre` to all invocations of
+`python3 -m pip install`.
+
+**NOTE:** PyPI has various other `pip`-installable packages with the word "sage" in their names.
+Some of them are maintained by the SageMath project, some are provided by SageMath users for
+various purposes, and others are entirely unrelated to SageMath. Do not use the packages
+`sage` and `sagemath`. For a curated list of packages, see the chapter
+[Packages and Features](https://doc.sagemath.org/html/en/reference/spkg/index.html) of the
+Sage Reference Manual.
 
 SageMath Docker images
 ----------------------

pkgs/sage-conf/_sage_conf/__main__.py

@@ -1,22 +1,19 @@
 # Entry point 'sage-config'.  It does not depend on any packages.
 
-from sage_conf import *
-
 def _main():
     from argparse import ArgumentParser
     from sys import exit, stdout
-    parser = ArgumentParser()
+
+    import sage_conf
+
+    parser = ArgumentParser(prog='sage-config')
     parser.add_argument('--version', help="show version", action="version",
-                       version='%(prog)s ' + VERSION)
+                       version='%(prog)s ' + sage_conf.VERSION)
     parser.add_argument("VARIABLE", nargs='?', help="output the value of VARIABLE")
     args = parser.parse_args()
-    d = globals()
     if args.VARIABLE:
-        stdout.write('{}\n'.format(d[args.VARIABLE]))
+        stdout.write('{}\n'.format(getattr(sage_conf, args.VARIABLE)))
     else:
-        for k, v in d.items():
+        for k in dir(sage_conf):
             if not k.startswith('_'):
-                stdout.write('{}={}\n'.format(k, v))
-
-if __name__ == "__main__":
-    _main()
+                stdout.write('{}={}\n'.format(k, getattr(sage_conf, k)))

pkgs/sage-conf/sage_conf.py

@@ -1,2 +1,6 @@
 from _sage_conf._conf import *
 from _sage_conf.__main__ import _main
+
+
+if __name__ == "__main__":
+    _main()