Rewrite installation instructions

docs/requirements.txt

@@ -3,3 +3,5 @@ myst-parser
 sphinx>=7.3
 sphinx-copybutton
 sphinxext-opengraph
+sphinx-design
+sphinx-reredirects

docs/source/conf.py

@@ -51,11 +51,22 @@
     "sphinx.ext.inheritance_diagram",
     "sphinxcontrib.programoutput",
     "myst_parser",
+    "sphinx_design",
+    "sphinx_reredirects",
 ]
 
 # Automatically generate stub pages when using the .. autosummary directive
 autosummary_generate = True
 
+myst_enable_extensions = ["colon_fence", "amsmath"]
+
+# redirects (for moved / deleted pages)
+redirects = {
+    "installation/linux": "uv.html",
+    "installation/macos": "uv.html",
+    "installation/windows": "uv.html",
+}
+
 # generate documentation from type hints
 ALIAS_DOCS_DICT = parse_module_attributes()[0]
 autodoc_typehints = "description"

docs/source/faq/installation.md

@@ -120,19 +120,24 @@ of [ManimPango's README](https://github.com/ManimCommunity/ManimPango).
 
 ---
 
+(not-on-path)=
 ## I am using Windows and get the error `X is not recognized as an internal or external command, operable program or batch file`
 
-Regardless of whether `X` says `python` or `manim`, this means that the executable you
-are trying to run is not located in one of the directories your system is looking
-for them (specified by the `PATH` variable). Take a look at the instructions
-{doc}`in the installation guide for Windows </installation/windows>`, or
-[this StackExchange answer](https://superuser.com/questions/143119/how-do-i-add-python-to-the-windows-path/143121#143121)
-to get help with editing the `PATH` variable manually.
+If you have followed {doc}`our local installation instructions </installation/uv>` and
+have not activated the corresponding virtual environment, make sure to use `uv run manim ...`
+instead of just `manim` (or activate the virtual environment by following the instructions
+printed when running `uv venv`).
 
-If `python` is recognized but not `manim` or `pip`, you can try running
+Otherwise there is a problem with the directories where your system is looking for
+executables (the `PATH` variable).
+If `python` is recognized, you can try running
 commands by prepending `python -m`. That is, `manim` becomes `python -m manim`,
 and `pip` becomes `python -m pip`.
 
+Otherwise see
+[this StackExchange answer](https://superuser.com/questions/143119/how-do-i-add-python-to-the-windows-path/143121#143121)
+to get help with editing the `PATH` variable manually.
+
 ---
 
 ## I have tried using Chocolatey (`choco install manimce`) to install Manim, but it failed!

docs/source/installation.rst

@@ -8,8 +8,8 @@ require no local installation. Head over to
 https://try.manim.community to give our interactive tutorial a try.
 
 Otherwise, if you intend to use Manim to work on an animation project,
-we recommend installing the library locally (either to a conda environment,
-your system's Python, or via Docker).
+we recommend installing the library locally (preferably to some isolated
+virtual Python environment, or a conda-like environment, or via Docker).
 
 .. warning::
 
@@ -19,13 +19,31 @@ your system's Python, or via Docker).
    versions <different-versions>` if you are unsure which
    version you should install.
 
+#. :ref:`(Recommended) Installing Manim via Python's package manager pip
+   <local-installation>`
 #. :ref:`Installing Manim to a conda environment <conda-installation>`
-#. :ref:`Installing Manim to your system's Python <local-installation>`
 #. :ref:`Using Manim via Docker <docker-installation>`
 #. :ref:`Interactive Jupyter notebooks via Binder / Google Colab
    <interactive-online>`
 
 
+.. _local-installation:
+
+Installing Manim locally via pip
+********************************
+
+The recommended way of installing Manim is by using Python's package manager
+pip. If you already have a Python environment set up, you can simply run
+``pip install manim`` to install the library.
+
+Our :doc:`local installation guide <installation/uv>` provides more detailed
+instructions, including best practices for setting up a suitable local environment.
+
+.. toctree::
+   :hidden:
+
+   installation/uv
+
 .. _conda-installation:
 
 Installing Manim via Conda and related environment managers
@@ -55,48 +73,6 @@ The following pages show how to install Manim in a conda environment:
    installation/conda
 
 
-
-.. _local-installation:
-
-Installing Manim locally
-************************
-
-Manim is a Python library, and it can be
-installed via `pip <https://pypi.org/project/manim/>`__
-or `conda <https://anaconda.org/conda-forge/manim/>`__. However,
-in order for Manim to work properly, some additional system
-dependencies need to be installed first. The following pages have
-operating system specific instructions for you to follow.
-
-Manim requires Python version ``3.9`` or above to run.
-
-.. hint::
-
-   Depending on your particular setup, the installation process
-   might be slightly different. Make sure that you have tried to
-   follow the steps on the following pages carefully, but in case
-   you hit a wall we are happy to help: either `join our Discord
-   <https://www.manim.community/discord/>`__, or start a new
-   Discussion `directly on GitHub
-   <https://github.com/ManimCommunity/manim/discussions>`__.
-
-.. toctree::
-   :maxdepth: 2
-
-   installation/windows
-   installation/macos
-   installation/linux
-
-Once Manim is installed locally, you can proceed to our
-:doc:`quickstart guide <tutorials/quickstart>` which walks you
-through rendering a first simple scene.
-
-As mentioned above, do not worry if there are errors or other
-problems: consult our :doc:`FAQ section </faq/index>` for help
-(including instructions for how to ask Manim's community for help).
-
-
-
 .. _docker-installation:
 
 Using Manim via Docker
@@ -140,6 +116,11 @@ If you're using Visual Studio Code you can install an extension called
 of the animation inside the editor. The extension can be installed through the
 `marketplace of VS Code <https://marketplace.visualstudio.com/items?itemName=Rickaym.manim-sideview>`__.
 
+.. caution::
+
+   This extension is not officially maintained by the Manim Community.
+   If you run into issues, please report them to the extension's author.
+
 
 Installation for developers
 ***************************

docs/source/installation/conda.rst

@@ -10,15 +10,25 @@ namely `conda <https://docs.conda.io/projects/conda/en/latest/user-guide/install
 
 After installing your package manager, you can create a new environment and install ``manim`` inside by running
 
-.. code-block:: bash
 
-   # using conda or mamba
-   conda create -n my-manim-environment
-   conda activate my-manim-environment
-   conda install -c conda-forge manim
-   # using pixi
-   pixi init
-   pixi add manim
+.. tab-set::
+
+   .. tab-item:: conda / mamba
+
+      .. code-block:: bash
+
+         # if you want to use mamba, just replace conda below with mamba
+         conda create -n my-manim-environment
+         conda activate my-manim-environment
+         conda install -c conda-forge manim
+
+   .. tab-item:: pixi
+
+      .. code-block:: bash
+
+         pixi init
+         pixi add manim
+
 
 Since all dependencies (except LaTeX) are handled by conda, you don't need to worry
 about needing to install additional dependencies.
@@ -32,11 +42,8 @@ In order to make use of Manim's interface to LaTeX to, for example, render
 equations, LaTeX has to be installed as well. Note that this is an optional
 dependency: if you don't intend to use LaTeX, you don't have to install it.
 
-You can install LaTeX by following the optional dependencies steps
-for :ref:`Windows <win-optional-dependencies>`,
-:ref:`Linux <linux-optional-dependencies>` or
-:ref:`macOS <macos-optional-dependencies>`.
-
+Recommendations on how to install LaTeX on different operating systems
+can be found :doc:`in our local installation guide </installation/uv>`.
 
 
 Working with Manim