address review comments

content/en/install.md

@@ -7,85 +7,156 @@ The recommended method of installing SciPy depends on your preferred workflow.
 The common workflows can roughly be broken down into the following
 categories:
 
-- [Environment-based (e.g. `pip`, `conda`)](#environment-based) (the traditional workflow)
 - [Project-based (e.g. `uv`, `pixi`)](#project-based) (recommended for new users)
-- [System package managers](#system-package-managers) (simplest)
+- [Environment-based (e.g. `pip`, `conda`)](#environment-based) (the traditional workflow)
+- [System package managers](#system-package-managers) (not recommended)
 - [Building from source](#building-from-source) (for debugging and development)
 
 To install SciPy with [static type stubs],
 see [Installing with type stubs](#type-stubs).
 
 [static type stubs]: https://typing.readthedocs.io/en/latest/guides/libraries.html
 
-<a name="environment-based"></a>
+<a name="project-based"></a>
 
-## Environment-based workflows
+## Project-based workflows
 
-In environment-based workflows, you install packages into an environment, which you
-can activate and deactivate.
+In project-based workflows, a project is a directory containing a manifest
+file describing the project, a lock-file describing the exact dependencies
+of the project, and the project's (potentially multiple) environments.
 
-If you have installed Python, you can create a virtual environment with a tool such
-as `venv` - see [the tutorial in the Python Packaging User Guide][venv-guide].
-You can then install [SciPy from PyPI], the Python Package Index, with [`pip`]:
+### Installing with `uv`
 
-    python -m pip install scipy
+{{< admonition tip >}}
+If it is your first time installing a Python library, start here!
+{{< /admonition >}}
 
-[venv-guide]: https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments
-[SciPy from PyPI]: https://pypi.org/project/scipy/
-[`pip`]: https://pip.pypa.io/en/stable/getting-started/
+Here is a step-by-step guide to setting up a project to try SciPy with [`uv`],
+a Python package manager.
 
-Alternatively, you can install [SciPy from conda-forge] using a [Conda]-based
-environment manager. You can install Python itself, as well as packages in
-languages other than Python, as Conda packages.
+[`uv`]: https://docs.astral.sh/uv/
 
-[Miniforge] is the recommended way to install `conda` and [`mamba`],
-two Conda-based environment managers. You can then install SciPy as follows:
+1. Install `uv`, following [the instructions in the `uv` documentation][install-uv].
 
-    conda install scipy # or
-    mamba install scipy
+[install-uv]: https://docs.astral.sh/uv/getting-started/installation/
 
-[SciPy from conda-forge]: https://anaconda.org/conda-forge/scipy
-[Miniforge]: https://conda-forge.org/download/
-[Conda]: https://docs.conda.io/projects/conda/en/latest/index.html
-[`mamba`]: https://mamba.readthedocs.io/en/latest/
+2. Create a new project in a new subdirectory, by executing the following in a terminal:
 
-<a name="project-based"></a>
+        uv init try-scipy
+        cd try-scipy
 
-## Project-based workflows
+    {{< admonition hint >}}
+    The second command changes directory into the directory of your project.
+    {{< /admonition >}}
 
-In project-based workflows, a project is a directory containing a manifest
-file describing the project, a lock-file describing the exact dependencies
-of the project, and the project's (potentially multiple) environments.
-These workflows provide reproducibility benefits over environment-based workflows.
+3. Install Python:
 
-You can add [SciPy from PyPI] to a [`uv`] project:
+        uv python install
 
-    uv add scipy
+    {{< admonition note >}}
+    If you have already installed Python, this step is optional.
+    {{< /admonition >}}
 
-You can also install Python itself with `uv`.
+4. Add SciPy to your project:
 
-[`uv`]: https://docs.astral.sh/uv/
+        uv add scipy
 
-If you work with non-Python packages, you may prefer to install SciPy as
-a Conda package, so that you can use the same workflow for packages which
-are not available on PyPI.
+5. Try out SciPy!
+
+        uv run python
+
+    This will launch a Python interpreter session, from which you can `import scipy`.
 
-You can add [SciPy from conda-forge] to a [`pixi`] project:
+See next steps in [the SciPy user guide][scipy-user-guide].
 
-    pixi add scipy
+[scipy-user-guide]: https://docs.scipy.org/doc/scipy/tutorial/
 
-Pixi can also install packages from PyPI, using `uv` under the hood.
+### Installing with `pixi`
 
+If you work with non-Python packages, you may prefer to install SciPy as
+a [Conda] package, so that you can use the same workflow for packages which
+are not available on [PyPI](https://pypi.org/), the Python Package Index.
+Conda can manage packages in any language, so you can use it to install
+Python itself, compilers, and other languages.
+
+[Conda]: https://docs.conda.io/projects/conda/en/latest/index.html
+
+The steps to install SciPy from [conda-forge] using the package management
+tool [`pixi`] are very similar to the steps for `uv`:
+
+[conda-forge]: https://conda-forge.org/
 [`pixi`]: https://pixi.sh/latest/
 
+1. Install `pixi`, following [the instructions in the `pixi` documentation][install-pixi].
+
+[install-pixi]: https://pixi.sh/latest/
+
+2. Create a new project in a new subdirectory:
+
+        pixi init try-scipy
+        cd try-scipy
+
+4. Add SciPy to your project:
+
+        uv add scipy
+
+    {{< admonition note >}}
+    This step also adds Python from conda-forge.
+    {{< /admonition >}}
+
+5. Try out SciPy!
+
+        pixi run python
+
+See next steps in [the SciPy user guide][scipy-user-guide].
+
+<a name="environment-based"></a>
+
+## Environment-based workflows
+
+In environment-based workflows, you install packages into an environment, which you
+can activate and deactivate.
+These workflows are well-established,
+but lack some reproducibility benefits of project-based workflows.
+
+### Installing with `pip`
+
+1. [Install Python](https://www.python.org/downloads/).
+
+2. Create and activate a virtual environment with `venv`.
+
+    {{< admonition hint >}}
+    See [the tutorial in the Python Packaging User Guide][venv-guide].
+    {{< /admonition >}}
+
+[venv-guide]: https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments
+
+3. Install SciPy, using [`pip`]:
+
+        python -m pip install scipy
+
+[`pip`]: https://pip.pypa.io/en/stable/getting-started/
+
+### Installing with `conda`
+
+[Miniforge] is the recommended way to install `conda` and [`mamba`],
+two Conda-based environment managers.
+You can then install SciPy from conda-forge as follows:
+
+    conda install scipy # or
+    mamba install scipy
+
+[Miniforge]: https://conda-forge.org/download/
+[`mamba`]: https://mamba.readthedocs.io/en/latest/
+
 <a name="system-package-managers"></a>
 
 ## Installing system-wide via a system package manager
 
 System package managers can install the most common Python packages.
 They install packages for the entire computer, often use older versions,
 and don't have as many available versions. They are not the recommended
-installation method, but they are the simplest.
+installation method.
 
 ### Ubuntu and Debian
 
@@ -123,29 +194,17 @@ For details on how to build from source, see
 ## Installing with type stubs
 
 Static type stubs are available via a separate package, `scipy-stubs`, on
-PyPI and conda-forge. If you have already installed SciPy, you just need to
-install `scipy-stubs` in the same way:
-
-    python -m pip install scipy-stubs # or
-    uv add scipy-stubs # or
-    conda install scipy-stubs # or
-    pixi add scipy-stubs
-
-<!---
-XXX: https://github.com/conda-forge/scipy-stubs-feedstock/pull/5
--->
-
+PyPI and conda-forge.
 You can also install SciPy and `scipy-stubs` as a single package,
 via the `scipy-stubs[scipy]` extra on PyPI, or the `scipy-typed`
 package on conda-forge.
 To get a specific version `x.y.z` of SciPy (such as `1.14.1`),
-you should install version `x.y.z.*` below:
+you should install version `x.y.z.*`, for example:
 
-    python -m pip install "scipy-stubs[scipy]" # or
-    # versions for illustrative purposes
     uv add "scipy-stubs[scipy]==1.14.1.*" # or
-    conda install "scipy-typed>=1.14" # or
-    pixi add "scipy-typed=1.15.0.*"
+    pixi add "scipy-typed=1.15.0.*" # or
+    python -m pip install "scipy-stubs[scipy]" # or
+    conda install "scipy-typed>=1.14"
 
 Please direct questions about static typing support to
 [the `scipy-stubs` GitHub repository](https://github.com/jorenham/scipy-stubs).