Update installation page

content/en/beginner-install.md

@@ -0,0 +1,78 @@
+---
+title: Beginner Installation Guide
+sidebar: false
+---
+
+{{< admonition tip >}}
+This is the beginner installation guide.
+If you are comfortable with using a terminal and happy to learn
+how to use a package manager, check out
+[the main installation guide](./install.md)!
+{{< /admonition >}}
+
+- [JupyterLite](#jupyterlite)
+- [Scientific Python Distributions](#distributions)
+- [Installing globally with `pip`](#pip-global)
+
+<a name="jupyterlite"></a>
+
+## JupyterLite
+
+To try out SciPy, you don't even need to install it!
+You can use SciPy in your browser at https://jupyter.org/try-jupyter/lab/ -
+just open a Python Notebook, then write `import scipy` in one of
+the notebook "cells" and hit play.
+
+For next steps, see [the SciPy user guide][scipy-user-guide].
+
+[scipy-user-guide]: https://docs.scipy.org/doc/scipy/tutorial/
+
+<a name="distributions"></a>
+
+## Scientific Python Distributions
+
+Python distributions provide the language itself, along with the most
+commonly used packages and tools. These downloadable files require
+little configuration, work on almost all setups, and provide all the
+most commonly used scientific Python tools.
+[Anaconda](https://www.anaconda.com/download/) works on Windows, Mac,
+and Linux, and is best suited to beginning users.
+Other options include:
+
+- [WinPython](https://winpython.github.io): Another free distribution
+  including scientific packages and the Spyder IDE; Windows only, but
+  more actively maintained and supports the latest Python 3 versions.
+- [Pyzo](https://pyzo.org): A free distribution based on Anaconda
+  and the IEP interactive development environment; Supports Linux,
+  Windows, and Mac.
+
+{{< admonition note >}}
+Anaconda is free to use for inviduals, universities, and companies smaller than
+200 employees. For more detail, see Anaconda's helpful blog on
+["when is Anaconda free to use?"](https://www.anaconda.com/blog/update-on-anacondas-terms-of-service-for-academia-and-research)
+{{< /admonition >}}
+
+After installing a scientific Python distribution,
+see next steps in [the SciPy user guide][scipy-user-guide].
+
+<a name="pip-global"></a>
+
+## Installing globally with `pip`
+
+If you already have Python installed, you can install SciPy globally
+(for all users on the system)
+with `pip` by executing the following in a terminal/shell:
+
+    python -m pip install scipy
+
+{{< admonition warning >}}
+You may see this recommended in tutorials or classes, but it is not
+recommended to install packages globally on your system.
+The recommended way to install SciPy with `pip` is to use a virtual
+environment - see [Installing with `pip`](./install.md#installing-with-pip).
+{{< /admonition >}}
+
+{{< admonition note >}}
+For more information on why this is not a recommended installation method,
+read about [virtual environments in the Python Packaging User Guide](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments).
+{{< /admonition >}}

content/en/install.md

@@ -3,101 +3,230 @@ title: Installation
 sidebar: false
 ---
 
-Installations methods include:
+{{< admonition tip >}}
+This page assumes that you are comfortable with using a terminal and happy to learn
+how to use a package manager. If you are a beginner and just want to get started
+with SciPy as quickly as possible, check out
+[the beginner installation guide](./beginner-install.md)!
+{{< /admonition >}}
 
-- [Distributions](#distributions)
-- [pip](#pip-install)
-- [conda](#pip-install)
-- [Package Manager](#package_manager)
-- [Source](#source)
+The recommended method of installing SciPy depends on your preferred workflow.
+The common workflows can roughly be broken down into the following
+categories:
 
-Methods differ in ease of use, coverage, maintenance of old versions,
-system-wide versus local environment use, and control. With pip or
-Anaconda\'s conda, you can control the package versions for a specific
-project to prevent conflicts. Conda also controls non-Python packages,
-like MKL or HDF5. System package managers, like `apt-get`, install
-across the entire computer, often have older versions, and don\'t have
-as many available versions. Source compilation is much more difficult
-but is necessary for debugging and development. If you don\'t know which
-installation method you need or prefer, we recommend the Scientific
-Python Distribution [Anaconda](https://www.anaconda.com/download/).
+- [Project-based (e.g. `uv`, `pixi`)](#project-based) (recommended for new users)
+- [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)
 
-<a name="distributions"></a>
+To install SciPy with [static type stubs],
+see [Installing with type stubs](#type-stubs).
 
-# Scientific Python Distributions (recommended)
+[static type stubs]: https://typing.readthedocs.io/en/latest/guides/libraries.html
 
-Python distributions provide the language itself, along with the most
-commonly used packages and tools. These downloadable files require
-little configuration, work on almost all setups, and provide all the
-commonly used scientific Python tools.
+<a name="project-based"></a>
 
-[Anaconda](https://www.anaconda.com/download/) works on Windows, Mac,
-and Linux, provides over 1,500 Python packages, and is used by over 15
-million people. Anaconda is best suited to beginning users; it provides
-a large collection of libraries all in one.
+## Project-based workflows
 
-For more advanced users who will need to install or upgrade regularly,
-[Mambaforge](https://github.com/conda-forge/miniforge#mambaforge) is a more
-suitable way to install the `conda` (and `mamba`, a faster `conda` alternative)
-package manager.
+### Installing with `uv`
 
-Other options include:
+Here is a step-by-step guide to setting up a project to use SciPy, with [`uv`],
+a Python package manager.
 
-- [WinPython](https://winpython.github.io): Another free distribution
-  including scientific packages and the Spyder IDE; Windows only, but
-  more actively maintained and supports the latest Python 3 versions.
-- [Pyzo](https://pyzo.org): A free distribution based on Anaconda
-  and the IEP interactive development environment; Supports Linux,
-  Windows, and Mac.
+[`uv`]: https://docs.astral.sh/uv/
 
-<a name="pip-install"></a>
+<!-- prettier-ignore-start -->
 
-# Installing with Pip
+1. Install `uv`, following [the instructions in the `uv` documentation][install-uv].
 
-You can install SciPy from PyPI with `pip`:
+[install-uv]: https://docs.astral.sh/uv/getting-started/installation/
 
-    python -m pip install scipy
+2.  Create a new project in a new subdirectory, by executing the following in a terminal:
 
-<a name="conda-install"></a>
+        uv init try-scipy
+        cd try-scipy
 
-# Installing via Conda
+    {{< admonition hint >}}
+The second command changes directory into the directory of your project.
+    {{< /admonition >}}
 
-You can install SciPy from the `defaults` or `conda-forge` channels with `conda`:
+3.  Add SciPy to your project:
 
-    conda install scipy
+        uv add scipy
 
-<a name="package_manager"></a>
+    {{< admonition note >}}
+This will automatically install Python if you don't already have it installed!
+    {{< /admonition >}}
 
-# Install system-wide via a package manager
+    {{< admonition tip >}}
+You can install other Python libraries in the same way, e.g.
+
+    uv add matplotlib
+
+    {{< /admonition >}}
+
+4.  Try out SciPy!
+
+        uv run python
+
+    This will launch a Python interpreter session, from which you can `import scipy`.
+
+<!-- prettier-ignore-end -->
+
+See next steps in [the SciPy user guide][scipy-user-guide].
+
+[scipy-user-guide]: https://docs.scipy.org/doc/scipy/tutorial/
+
+{{< admonition note >}}
+
+After rebooting your computer, you'll want to navigate to your `try-scipy`
+project directory and execute `uv run python` to drop back into a Python interpreter
+with SciPy importable.
+To execute a Python script, you can use `uv run myscript.py`.
+
+Read more at [the uv guide to working on projects][uv-projects].
+
+[uv-projects]: https://docs.astral.sh/uv/guides/projects/
+
+{{< /admonition >}}
+
+### 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
+
+3.  Add SciPy to your project:
+
+        pixi add scipy
+
+4.  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 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.
+
+In contrast,
+in environment-based workflows you install packages into an environment,
+which you can activate and deactivate from any directory.
+These workflows are well-established,
+but lack some reproducibility benefits of project-based workflows.
+
+### Installing with `pip`
+
+<!-- prettier-ignore-start -->
+
+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](https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments).
+    {{< /admonition >}}
+
+3.  Install SciPy, using [`pip`]:
+
+        python -m pip install scipy
+
+<!-- prettier-ignore-end -->
+
+[`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.
+After creating an environment, you can 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.
+and don't have as many available versions. They are not the recommended
+installation method.
 
-## Ubuntu and Debian
+### Ubuntu and Debian
 
 Using `apt-get`:
 
     sudo apt-get install python3-scipy
 
-## Fedora
+### Fedora
 
 Using `dnf`:
 
     sudo dnf install python3-scipy
 
-## macOS
+### macOS
 
 macOS doesn't have a preinstalled package manager, but you can install
 [Homebrew](https://brew.sh/) and use it to install SciPy (and Python itself):
 
     brew install scipy
 
-<a name="source"></a>
+<a name="building-from-source"></a>
 
-# Source packages
+## Building from source
 
 A word of warning: building SciPy from source can be a nontrivial exercise. We
-recommend using binaries instead if those are available for your platform.
+recommend using binaries instead if those are available for your platform
+via one of the above methods.
 For details on how to build from source, see
-[this guide in the SciPy docs](https://scipy.github.io/devdocs/building/index.html).
+[the building from source guide in the SciPy docs][building-docs].
+
+[building-docs]: https://scipy.github.io/devdocs/building/index.html
+
+<a name="type-stubs"></a>
+
+## Installing with type stubs
+
+Static type stubs are available via a separate package, `scipy-stubs`, on
+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.*`, for example:
+
+    uv add "scipy-stubs[scipy]==1.14.1.*" # or
+    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).