Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Reworked installation instructions (#1949)

Benjamin Hackl89bcec8f2f19
diff --git a/docs/source/_static/windows_cairo.png b/docs/source/_static/windows_cairo.png
deleted file mode 100644
index e9691edda..000000000
Binary files a/docs/source/_static/windows_cairo.png and /dev/null differ
diff --git a/docs/source/_static/windows_miktex.png b/docs/source/_static/windows_miktex.png
deleted file mode 100644
index 9189428a1..000000000
Binary files a/docs/source/_static/windows_miktex.png and /dev/null differ
diff --git a/docs/source/_static/windows_sox.png b/docs/source/_static/windows_sox.png
deleted file mode 100644
index 27fae80d3..000000000
Binary files a/docs/source/_static/windows_sox.png and /dev/null differ
diff --git a/docs/source/contributing/development.rst b/docs/source/contributing/development.rst
index 78817babe..831fb375f 100644
--- a/docs/source/contributing/development.rst
+++ b/docs/source/contributing/development.rst
@@ -47,9 +47,36 @@ For first-time contributors
- ``upstream`` the ManimCommunity repository
#. Install Manim:
-
- - See our :doc:`instructions for developers<../installation/for_dev>` for
- details and continue here afterwards.
+
+ - Follow the steps in our :doc:`installation instructions
+ <../installation>` to install **Manim's dependencies**,
+ primarily ``ffmpeg`` and ``LaTeX``.
+
+ - We recommend using `Poetry <https://python-poetry.org>`__ to manage your
+ developer installation of Manim. Poetry is a tool for dependency
+ management and packaging in Python. It allows you to declare the libraries
+ your project depends on, and it will manage (install / update) them
+ for you. In addition, Poetry provides a simple interface for
+ managing virtual environments.
+
+ If you choose to use Poetry as well, follow `Poetry's installation
+ guidelines <https://python-poetry.org/docs/master/#installation>`__
+ to install it on your system, then run ``poetry install`` from
+ your cloned repository. Poetry will then install Manim, as well
+ as create and enter a virtual environment. You can always re-enter
+ that environment by running ``poetry shell``.
+
+ - In case you decided against Poetry, you can install Manim via pip
+ by running ``python3 -m pip install .``. Note that due to our
+ development infrastructure being based on Poetry, we currently
+ do not support editable installs via ``pip``, so you will have
+ to re-run this command every time you make changes to the source
+ code.
+
+ .. note::
+
+ The following steps assume that you chose to install and work with
+ Poetry.
#. Install Pre-Commit:
diff --git a/docs/source/index.rst b/docs/source/index.rst
index c0327a1b2..c65a077cd 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -61,6 +61,7 @@ information here will make it easier for newcomers to get started using
examples
changelog
reference
+ plugins
reporting_bugs
contributing
conduct
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index d4b7743a2..9c7f2f3ed 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -1,64 +1,113 @@
Installation
============
-Manim has a few dependencies that need to be installed before it can be used.
-The following pages have instructions that are specific to your system. Once
-you are done installing the dependencies, come back to this page to install
-manim itself.
+Depending on your use case, different installation options are recommended:
+if you just want to play around with Manim for a bit, interactive in-browser
+notebooks are a really simple way of exploring the library as they
+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 your system's
+Python, or via Docker).
.. warning::
- These instructions are for the *community edition* of Manim **only**. Trying
- to use these instructions to install
- `3b1b/manim <https://github.com/3b1b/manim>`_ or instructions there to install
- this version will cause problems. Read the :doc:`Differences between Manim
- Versions <installation/versions>` and decide which version you wish to
- install, then only follow the instructions for your desired version.
+ Note that there are several different versions of Manim. The
+ instructions on this website are **only** for the *community edition*.
+ Find out more about the :doc:`differences between Manim
+ versions <installation/versions>` if you are unsure which
+ version you should install.
-.. tip::
+#. :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>`
- In case that you want to try manim online without installation, open it in
- `Binder <https://mybinder.org/v2/gh/ManimCommunity/jupyter_examples/HEAD?filepath=basic_example_scenes.ipynb>`_.
+.. _local-installation:
-Installing dependencies
-***********************
+Installing Manim locally
+************************
+
+Manim is a Python library, and it can be
+`installed via pip <https://pypi.org/project/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.
+
+.. 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/versions
- installation/win
- installation/mac
+ installation/windows
+ installation/macos
installation/linux
- installation/colab
installation/troubleshooting
- installation/for_dev
- installation/plugins
+
+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:`troubleshooting
+guide <installation/troubleshooting>` for help, or get in touch
+with the community via `GitHub discussions
+<https://github.com/ManimCommunity/manim/discussions>`__ or
+`Discord <https://www.manim.community/discord/>`__.
+
-.. _installing-manim:
+.. _docker-installation:
-Installing Manim
-****************
+Using Manim via Docker
+**********************
+
+`Docker <https://www.docker.com>`__ is a virtualization tool that
+allows the distribution of encapsulated software environments (containers).
+
+The following pages contain more information about the docker image
+maintained by the community, ``manimcommunity/manim``:
+
+.. toctree::
-Manim Community runs on Python 3.7+. If you'd like to just use the library, you
-can install it from PyPI via pip:
+ installation/docker
-.. code-block:: bash
- pip install manim
+.. _interactive-online:
-You can replace ``pip`` with ``pip3`` if you need to in your system.
+Interactive Jupyter notebooks for your browser
+**********************************************
-Alternatively, you can work with Manim using our Docker image that can be
-found at `Docker Hub <https://hub.docker.com/r/manimcommunity/manim>`_.
+Manim ships with a built-in ``%%manim`` IPython magic command
+designed for the use within `Jupyter notebooks <https://jupyter.org>`__.
+Our interactive tutorial over at https://try.manim.community illustrates
+how Manim can be used from within a Jupyter notebook.
-Installation For Developers
+The following pages explain how you can setup interactive environments
+like that yourself:
+
+.. toctree::
+
+ installation/jupyter
+
+
+Installation for developers
***************************
-If you want to contribute to manim, follow the :doc:`contributing` instructions.
-Verifying installation
-**********************
-Please proceed to our :doc:`quickstart guide <tutorials/quickstart>` to run a simple file to test your installation.
-If it did not work, please refer to our :doc:`troubleshooting guide <installation/troubleshooting>` for help.
+In order to change code in the library, it is recommended to
+install Manim in a different way. Please follow the instructions
+in our :doc:`contribution guide <contributing>` if you are
+interested in that.
+
+
+
diff --git a/docs/source/installation/colab.rst b/docs/source/installation/colab.rst
deleted file mode 100644
index e3f865608..000000000
--- a/docs/source/installation/colab.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-Google Colaboratory
-===================
-
-You can install Manim in a `Google Colaboratory <https://colab.research.google.com/>`__ environment by running the following in a cell:
-
-.. code-block::
-
- !sudo apt update
- !sudo apt install libcairo2-dev ffmpeg texlive texlive-latex-extra texlive-fonts-extra texlive-latex-recommended texlive-science tipa libpango1.0-dev
- !pip install manim
- !pip install IPython --upgrade
-
-After the execution has completed, you will be prompted to restart the runtime. Click the "restart runtime" button at the bottom of the cell output.
-
-In the next cell, import manim like so:
-
-.. code-block::
-
- from manim import *
-
-Try and run the following code in the next cell to confirm installation.
-
-.. code-block::
-
- %%manim SquareToCircle
-
- class SquareToCircle(Scene):
- def construct(self):
- circle = Circle()
- circle.set_fill(PINK, opacity=0.5)
- self.play(Create(circle))
diff --git a/docs/source/installation/docker.rst b/docs/source/installation/docker.rst
new file mode 100644
index 000000000..66cb43db0
--- /dev/null
+++ b/docs/source/installation/docker.rst
@@ -0,0 +1,78 @@
+Docker
+======
+
+The community maintains a docker image, which can be found
+`on DockerHub <https://hub.docker.com/r/manimcommunity/manim>`__.
+For our image ``manimcommunity/manim``, there are the following tags:
+
+- ``latest``: the most recent version corresponding
+ to `the main branch <https://github.com/ManimCommunity/manim>`__,
+- ``stable``: the latest released version (according to
+ `the releases page <https://github.com/ManimCommunity/manim/releases>`__),
+- ``vX.Y.Z``: any particular released version (according to
+ `the releases page <https://github.com/ManimCommunity/manim/releases>`__).
+
+.. note::
+
+ When using Manim's CLI within a Docker container, some flags like
+ ``-p`` (preview file) and ``-f`` (show output file in the file browser)
+ are not supported.
+
+
+Basic usage of the Docker container
+-----------------------------------
+
+Assuming that you can access the docker installation on your system
+from a terminal (bash / PowerShell) via ``docker``, you can
+render a scene ``CircleToSquare`` in a file `test_scenes.py`
+with the following command.
+
+.. code-block:: bash
+
+ docker run --rm -it -v "/full/path/to/your/directory:/manim" manimcommunity/manim manim -qm test_scenes.py CircleToSquare
+
+.. tip::
+
+ For Linux users there might be permission problems when letting the
+ user in the container write to the mounted volume.
+ Add ``--user="$(id -u):$(id -g)"`` to the ``docker`` CLI arguments
+ to prevent the creation of output files not belonging to your user.
+
+
+Instead of using the "throwaway container" approach outlined
+above, you can also create a named container that you can
+modify to your liking. First, run
+
+.. code-block:: sh
+
+ docker run -it --name my-manim-container -v "/full/path/to/your/directory:/manim" manimcommunity/manim /bin/bash
+
+
+to obtain an interactive shell inside your container allowing you
+to, e.g., install further dependencies (like texlive packages using
+``tlmgr``). Exit the container as soon as you are satisfied. Then,
+before using it, start the container by running
+
+.. code-block:: sh
+
+ docker start my-manim-container
+
+which starts the container in the background. Then, to render
+a scene ``CircleToSquare`` in a file ``test_scenes.py``, run
+
+.. code-block:: sh
+
+ docker exec -it my-manim-container manim -qm test_scenes.py CircleToSquare
+
+
+Running JupyterLab via Docker
+-----------------------------
+
+Another alternative to using the Docker image is to spin up a
+local JupyterLab instance. To do that, simply run
+
+.. code-block:: sh
+
+ docker run -it -p 8888:8888 manimcommunity/manim jupyter lab --ip=0.0.0.0
+
+and then follow the instructions in the terminal.
\ No newline at end of file
diff --git a/docs/source/installation/for_dev.rst b/docs/source/installation/for_dev.rst
deleted file mode 100644
index e30600970..000000000
--- a/docs/source/installation/for_dev.rst
+++ /dev/null
@@ -1,131 +0,0 @@
-For Developers
-==============
-
-This documentation is for developers who want to contribute to
-`ManimCommunity/manim <https://github.com/ManimCommunity/manim>`_.
-
-Thank you for your interest in contributing! Please see our documentation on
-:doc:`../contributing` to take the necessary steps before installing Manim as a
-developer. This documentation assumes you have already taken the necessary
-steps to clone your fork.
-
-.. warning::
-
- If you have installed a non-developer version of manim, please uninstall
- it. This is to avoid any accidental usage of the non-developer version
- when developing and testing your local copy of the repository. This
- warning doesn't apply to users who use `poetry
- <https://python-poetry.org>`_ (chapter below.)
-
-For Developers with Poetry (Recommended)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Poetry is a tool for dependency management and packaging in Python. It allows to
-declare the libraries your project depends on and it will manage (install/update) them
-for you. In addition, Poetry provides a simple interface for managing virtual environments.
-
-Please follow `Poetry's installation guidelines
-<https://python-poetry.org/docs/master/#installation>`_
-in order to get Poetry up and running on your system.
-
-Installing System Dependencies
-******************************
-
-Please follow the instructions under :ref:`installing-manim` to install all
-dependencies (e.g. ``LaTeX``, ``ffmpeg``, etc.). Afterwards, proceed with the
-installation with Poetry.
-
-.. important:: Windows users can skip the steps to install Pycairo.
-
-
-.. _install-manim-poetry:
-
-Installing Manim using Poetry
-*****************************
-
-#. First start by cloning the `manim repository <https://github.com/manimcommunity/manim>`_
- (see the first few steps in :doc:`../contributing/development` for more details),
- then navigate into the freshly cloned directory in the terminal.
-
-#. Use the following command to install python dependencies. This will use the system python:
-
- .. code-block:: bash
-
- poetry install
-
- .. note:: The first time running this command, poetry will create and
- enter a virtual environment rooted in the current directory.
-
- For more information, you can visit the `poetry documentation
- <https://python-poetry.org/docs/managing-environments/>`_.
-
-#. If you exit the virtual environment, you can reactivate the
- ``Poetry`` virtual environment with:
-
- .. code-block:: bash
-
- poetry shell
-
- If you only need to run a single command, use:
-
- .. code-block:: bash
-
- poetry run <your-command>
-
-Now you are free to start developing!
-
-Running the Tests Using Poetry
-******************************
-
-After completing :ref:`install-manim-poetry`, you can run manim's test suite
-by activating a shell using ``poetry shell`` command and then running the
-command ``pytest`` to run the tests.
-
-.. code-block:: bash
-
- poetry shell
- pytest
-
-.. important::
-
- You should always run the test suite before making a PR. See
- :doc:`../contributing` for details.
-
-
-Code Formatting and Linting Using Poetry
-****************************************
-
-Once you are done with :ref:`install-manim-poetry`, you can run the code
-formatter ``black`` by activating entering the virtual environment:
-
-.. code-block:: bash
-
- poetry shell
- black manim
-
-Or alternatively, without entering the virtual environment:
-
-.. code-block:: bash
-
- poetry run black manim
-
-For example, if you have written some new example and want to format it and see
-lint information use the commands below.
-
-.. code-block:: bash
-
- poetry run black example_scenes
-
-Similarly, you can see linting information for a given file, or directory,
-by the ``black`` command with ``pylint``.
-
-
-For Developers with pip
-~~~~~~~~~~~~~~~~~~~~~~~
-
-.. code-block:: bash
-
- python3 -m pip install .
-
-Please see :doc:`../contributing` for more details about contributing to Manim.
-Since `pip` doesn't implement editable installations from our ``pyproject.toml``
diff --git a/docs/source/installation/jupyter.rst b/docs/source/installation/jupyter.rst
new file mode 100644
index 000000000..0680b0c93
--- /dev/null
+++ b/docs/source/installation/jupyter.rst
@@ -0,0 +1,102 @@
+Jupyter Notebooks
+=================
+
+
+Binder
+------
+
+`Binder <https://mybinder.readthedocs.io/en/latest/>`__ is an online
+platform that hosts shareable and customizable computing environments
+in the form of Jupyter notebooks. Manim ships with a built-in ``%%manim``
+Jupyter magic command which makes it easy to use in these notebooks.
+
+To see an example for such an environment, visit our interactive
+tutorial over at https://try.manim.community/.
+
+It is relatively straightforward to prepare your own notebooks in
+a way that allows them to be shared interactively via Binder as well:
+
+#. First, prepare a directory containing one or multiple notebooks
+ which you would like to share in an interactive environment. You
+ can create these notebooks by using Jupyter notebooks with a
+ local installation of Manim, or also by working in our pre-existing
+ `interactive tutorial environment <https://try.manim.community/>`__.
+#. In the same directory containing your notebooks, add a
+ file named ``Dockerfile`` with the following content:
+
+ .. code-block:: dockerfile
+
+ FROM manimcommunity/manim:v0.9.0
+
+ COPY --chown=manimuser:manimuser . /manim
+
+ Don't forget to change the version tag ``v0.9.0`` to the version you
+ were working with locally when creating your notebooks.
+#. Make the directory with your worksheets and the ``Dockerfile``
+ available to the public (and in particular: to Binder!). There are
+ `several different options to do so
+ <https://mybinder.readthedocs.io/en/latest/introduction.html#how-can-i-prepare-a-repository-for-binder>`__,
+ within the community we usually work with GitHub
+ repositories or gists.
+#. Once your material is publicly available, visit
+ https://mybinder.org and follow the instructions there to
+ generate an interactive environment for your worksheets.
+
+.. hint::
+
+ The repository containing our `interactive tutorial
+ <https://try.manim.community>`__ can be found at
+ https://github.com/ManimCommunity/jupyter_examples.
+
+
+Google Colaboratory
+-------------------
+
+It is also possible to install Manim in a
+`Google Colaboratory <https://colab.research.google.com/>`__ environment.
+In contrast to Binder, where you can customize and prepare the environment
+beforehand (such that Manim is already installed and ready to be used), you
+will have to take care of that every time you start
+a new notebook in Google Colab. Fortunately, this
+is not particularly difficult.
+
+After creating a new notebook, paste the following code block in a cell,
+then execute it.
+
+.. code-block::
+
+ !sudo apt update
+ !sudo apt install libcairo2-dev ffmpeg \
+ texlive texlive-latex-extra texlive-fonts-extra \
+ texlive-latex-recommended texlive-science \
+ tipa libpango1.0-dev
+ !pip install manim
+ !pip install IPython --upgrade
+
+You should start to see Colab installing all the dependencies specified
+in these commands. After the execution has completed, you will be prompted
+to restart the runtime. Click the "restart runtime" button at the bottom of
+the cell output. You are now ready to use Manim in Colab!
+
+To check that everything works as expected, first import Manim by running
+
+.. code-block::
+
+ from manim import *
+
+in a new code cell. Then create another cell containing the
+following code::
+
+ %%manim -qm -v WARNING SquareToCircle
+
+ class SquareToCircle(Scene):
+ def construct(self):
+ square = Square()
+ circle = Circle()
+ circle.set_fill(PINK, opacity=0.5)
+ self.play(Create(square))
+ self.play(Transform(square, circle))
+ self.wait()
+
+Upon running this cell, a short animation transforming a square
+into a circle should be rendered and displayed.
diff --git a/docs/source/installation/linux.rst b/docs/source/installation/linux.rst
index 6ee9e42b3..6b56edf92 100644
--- a/docs/source/installation/linux.rst
+++ b/docs/source/installation/linux.rst
@@ -1,174 +1,149 @@
Linux
=====
-The following instructions are given for different Linux distributions that use
-different package managers. After executing the instructions corresponding to
-your distribution, go to `Certifying a clean install`_ to check whether the
-dependencies are installed correctly. All distributions will follow the same
-instructions in `Certifying a clean install`_.
+The installation instructions depend on your particular operating
+system and package manager. If you happen to know exactly what you are doing,
+you can also simply ensure that your system has:
-The two necessary dependencies are cairo and ffmpeg. LaTeX is strongly
-recommended, as it is necessary to have access to the ``Tex`` and ``MathTex`` classes.
+- a reasonably recent version of Python 3 (3.7 or above),
+- with working Cairo bindings in the form of
+ `pycairo <https://cairographics.org/pycairo/>`__,
+- FFmpeg accessible from the command line as ``ffmpeg``,
+- and `Pango <https://pango.gnome.org>`__ headers.
-Ubuntu/Mint/Debian
-******************
-
-Before installing anything, make sure that your system is up to date.
-
-.. code-block:: bash
-
- sudo apt update
- sudo apt upgrade
-
-To install cairo:
+Then, installing Manim is just a matter of running:
.. code-block:: bash
- sudo apt install libcairo2-dev
-
-To install Pango:
-
-.. code-block:: bash
+ pip3 install manim
- sudo apt install libpango1.0-dev
+.. note::
-To install ffmpeg:
+ In light of the current efforts of migrating to rendering via OpenGL,
+ this list might be incomplete. Please `let us know
+ <https://github.com/ManimCommunity/manim/issues/new/choose>` if you
+ ran into missing dependencies while installing.
+
+In any case, we have also compiled instructions for several common
+combinations of operating systems and package managers below.
-.. code-block:: bash
+Required Dependencies
+---------------------
- sudo apt install ffmpeg
+apt – Ubuntu / Mint / Debian
+****************************
-To install LaTeX:
-(For minimal LaTeX installation, see `TinyTex Installation`_)
+To first update your sources, and then install Cairo, Pango, and FFmpeg
+simply run:
.. code-block:: bash
- sudo apt install texlive texlive-latex-extra texlive-fonts-extra \
- texlive-latex-recommended texlive-science texlive-fonts-extra tipa
+ sudo apt update
+ sudo apt install libcairo2-dev libpango1.0-dev ffmpeg
-If you don't have python3-pip installed, install it:
+If you don't have python3-pip installed, install it via:
.. code-block:: bash
sudo apt install python3-pip
-
-.. note:: These instructions are also valid for other Debian-based
- distributions or distributions that use the ``apt`` package manager.
-
-
-Fedora/CentOS/RHEL
-******************
-
-To install cairo:
-
-.. code-block:: bash
-
- sudo dnf install cairo-devel
-To install Pango:
+Then, to install Manim, run:
.. code-block:: bash
- sudo dnf install pango-devel
+ pip3 install manim
-To install ffmpeg, you have to add RPMfusion repository (If it's not already added). Please follow the instructions for your specific distribution in the following URL:
+Continue by reading the :ref:`optional dependencies <linux-optional-dependencies>`
+section.
-https://rpmfusion.org/Configuration/
+dnf – Fedora / CentOS / RHEL
+****************************
-Install ffmpeg from RPMfusion repository:
+To install Cairo and Pango:
.. code-block:: bash
- sudo dnf install ffmpeg
+ sudo dnf install cairo-devel pango-devel
-Install python development headers in order to successfully build pycairo wheel:
+In order to successfully build the ``pycairo`` wheel, you will also
+need the Python development headers:
.. code-block:: bash
sudo dnf install python3-devel
-To install LaTeX:
-(For minimal LaTeX installation, see `TinyTex Installation`_)
-
-.. code-block:: bash
-
- sudo dnf install texlive-scheme-medium
-
-
-Arch/Manjaro
-************
-
-Before installing anything, make sure that your system is up to date.
+FFmpeg is only available via the RPMfusion repository which you have to
+configure first – please consult https://rpmfusion.org/Configuration/ for
+instructions. Then, install FFmpeg:
.. code-block:: bash
- sudo pacman -Syu
+ sudo dnf install ffmpeg
-To install cairo:
+At this point you have all required dependencies and can install
+Manim by running:
.. code-block:: bash
- sudo pacman -S cairo
-
-To install pango:
+ pip3 install manim
-.. code-block:: bash
+Continue by reading the :ref:`optional dependencies <linux-optional-dependencies>`
+section.
- sudo pacman -S pango
+pacman – Arch / Manjaro
+***********************
-To install ffmpeg:
+.. tip::
-.. code-block:: bash
+ Thanks to *groctel*, there is a `dedicated Manim package
+ on the AUR! <https://aur.archlinux.org/packages/manim/>`
- sudo pacman -S ffmpeg
-
-To install LaTeX:
-(For minimal LaTeX installation, see `TinyTex Installation`_)
+If you don't want to use the packaged version from AUR, here is what
+you need to do manually: Update your package sources, then install
+Cairo, Pango, and FFmpeg:
.. code-block:: bash
- sudo pacman -S texlive-most
+ sudo pacman -Syu
+ sudo pacman -S cairo pango ffmpeg
-If you don't have python-pip installed, install it:
+If you don't have ``python-pip`` installed, get it by running:
.. code-block:: bash
sudo pacman -S python-pip
+then simply install Manim via:
-.. note:: These instructions are also valid for other Arch-based
- distributions or distributions that use the ``pacman`` package
- manager.
+.. code-block:: bash
-TinyTex Installation
-********************
+ pip3 install manim
-If you do not want to install full LaTeX (~2GB), you can install TinyTex (~500MB)
-and some extra packages for a minimal LaTeX installation. This is what done for
-choco ``manim-latex`` package for Windows.
-Install `TinyTex`_ and make sure to add ``bin`` folder created in your home
-directory to your ``PATH``.
+Continue by reading the :ref:`optional dependencies <linux-optional-dependencies>`
+section.
-For extra packages, see "Files > tools\chocolateyinstall.ps1" `here`_ and
-find ``tlmgr install ...`` command. Run that in terminal and
-finally ``tlmgr path add`` to add all the symlinks correctly.
-.. _TinyTex: https://yihui.org/tinytex/#for-other-users
-.. _here: https://community.chocolatey.org/packages/manim-latex#files
+.. _linux-optional-dependencies:
+Optional Dependencies
+---------------------
-Certifying a clean install
-**************************
+In order to make use of Manim's interface to LaTeX for, e.g., rendering
+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.
-To check that all dependencies have been installed properly, you can execute
-the commands ``ffmpeg -version`` and ``latex``. (If LaTeX is installed
-properly, you will be taken to a command-line program that captures your
-cursor. Press CTRL+C to exit.)
+You can use whichever LaTeX distribution you like or whichever is easiest
+to install with your package manager. Usually,
+`TeX Live <https://www.tug.org/texlive/>`__ is a good candidate if you don't
+care too much about disk space.
-.. note:: Note the LaTeX installation may take up a lot of space. The manim
- community developers are currently working on providing a simpler,
- lighter LaTeX package for you to install.
+Should you choose to work with some smaller TeX distribution like
+`TinyTeX <https://yihui.org/tinytex/>`__ , the full list
+of LaTeX packages which Manim interacts with in some way (a subset might
+be sufficient for your particular application) is::
-After making sure you have a clean install, you can go back to
-:ref:`installing-manim`.
+ amsmath babel-english cbfonts-fd cm-super ctex doublestroke dvisvgm everysel
+ fontspec frcursive fundus-calligra gnu-freefont jknapltx latex-bin
+ mathastext microtype ms physics preview ragged2e relsize rsfs
+ setspace standalone tipa wasy wasysym xcolor xetex xkeyval
diff --git a/docs/source/installation/mac.rst b/docs/source/installation/mac.rst
deleted file mode 100644
index 0eec84fda..000000000
--- a/docs/source/installation/mac.rst
+++ /dev/null
@@ -1,80 +0,0 @@
-Mac
-===
-
-First, you need to install Homebrew. Homebrew is a package manager similar to
-``apt`` or ``pacman`` on linux that allows you to install packages easily. If
-it is not installed, please install it with this command (for Apple Silicon useres, please read the tip first):
-
-.. code-block:: bash
-
- ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" < /dev/null 2> /dev/null
-
-
-.. tip::
-
- As of February 2020, the installation with ``brew`` has some issues with scipy and cairo packages in Apple Silicon mode. This can be solved by installing brew in the rosetta2 mode.
- Therefore, a rosetta terminal needs to be created (see here: https://5balloons.info/correct-way-to-install-and-use-homebrew-on-m1-macs/). In case you installed ``brew`` in the normal terminal before, you have to make sure you are using the correct brew when installing packages. On default, the rosetta brew is located at "/usr/local/bin/brew" and the Apple Silicon brew is located at "/opt/homebrew/bin/brew" (For more details on this, visit
- https://stackoverflow.com/questions/64882584/how-to-run-the-homebrew-installer-under-rosetta-2-on-m1-macbook ). Next, install cairo, ffmpeg and mactex as described below with the rosetta brew. If not already there, install python 3.9 with ``brew install [email protected]``. Finally, make sure that you are using the right pip version to install manim, for example by running ``/usr/local/opt/[email protected]/bin/python3.9 -m pip install manim``.
-
-
-
-
-To install cairo:
-
-.. code-block:: bash
-
- brew install cairo
-
-To install ffmpeg:
-
-.. code-block:: bash
-
- brew install ffmpeg
-
-To install LaTeX:
-
-.. code-block:: bash
-
- brew install --cask mactex
-
-.. warning:: Note that MacTeX will require at least 4.5GB of hard disk space.
- This is due to the fact that it installs every LaTeX addon package
- offered by `CTAN <https://ctan.org/>`_. Only a few of these
- packages are required by Manim. If you would like a smaller LaTeX
- install which only contains the packages needed by Manim alone,
- consider installing BasicTeX with the instructions below. This
- will require only about 1.5GB of space. If you have installed
- MacTeX and are comfortable with it, do not install BasicTeX.
-
-(Alternative) To install BasicTeX:
-
-.. code-block:: bash
-
- brew install --cask basictex
-
-Ensure that the TeXLiveManager tool ``tlmgr`` works by running ``tlmgr
---version`` in the terminal (a reboot might be necessary). Now update ``tlmgr``
-
-.. code-block:: bash
-
- sudo tlmgr update --self
-
-Finally, run
-
-.. code-block:: bash
-
- sudo tlmgr install standalone preview doublestroke relsize fundus-calligra \
- wasysym physics dvisvgm rsfs wasy cm-super
-
-
-Certifying a clean install
-**************************
-
-To check that all dependencies have been installed properly, you can execute
-the commands ``ffmpeg -version`` and ``latex`` (regardless of whether you
-installed MacTeX or BasicTeX). If LaTeX is installed properly, you will be
-taken to a command-line program that captures your cursor. Press CTRL+C to
-exit.
-
-After making sure you have a clean install, you can go back to
-:ref:`installing-manim`.
diff --git a/docs/source/installation/macos.rst b/docs/source/installation/macos.rst
new file mode 100644
index 000000000..e212d3aa7
--- /dev/null
+++ b/docs/source/installation/macos.rst
@@ -0,0 +1,100 @@
+MacOS
+=====
+
+For the sake of simplicity, the following instructions assume that you have
+the popular `package manager Homebrew <https://brew.sh>`__ installed. While
+you can certainly also install all dependencies without it, using Homebrew
+makes the process much easier.
+
+If you want to use Homebrew but do not have it installed yet, please
+follow `Homebrew's installation instructions <https://docs.brew.sh/Installation>`__.
+
+.. note::
+
+ For a while after Apple released its new ARM-based processors (the *"M1 chip"*),
+ the recommended way of installing Manim relied on *Rosetta*, Apple's compatibility
+ layer between Intel and ARM architectures. This is no longer necessary, Manim can
+ (and is recommended to) be installed natively.
+
+
+Required Dependencies
+---------------------
+
+To install all required dependencies for installing Manim (namely: ffmpeg, Python,
+and some required Python packages), run:
+
+.. code-block:: bash
+
+ brew install py3cairo ffmpeg
+
+On *Apple Silicon* based machines (i.e., devices with the M1 chip or similar; if
+you are unsure which processor you have check by opening the Apple menu, select
+*About This Mac* and check the entry next to *Chip*), some additional dependencies
+are required, namely:
+
+.. code-block:: bash
+
+ brew install cmake pango scipy
+
+After all required dependencies are installed, simply run:
+
+.. code-block:: bash
+
+ pip3 install manim
+
+to install Manim.
+
+.. note::
+
+ A frequent source for installation problems is if ``pip3``
+ does not point to the correct Python installation on your system.
+ To check this, run ``pip3 -V``: for MacOS Intel, the path should
+ start with ``/usr/local``, and for Apple Silicon with
+ ``/opt/homebrew``. If this is not the case, you either forgot
+ to modify your shell profile (``.zprofile``) during the installation
+ of Homebrew, or did not reload your shell (e.g., by opening a new
+ terminal) after doing so. It is also possible that some other
+ software (like Pycharm) changed the ``PATH`` variable – to fix this,
+ make sure that the Homebrew-related lines in your ``.zprofile`` are
+ at the very end of the file.
+
+
+Optional Dependencies
+---------------------
+
+In order to make use of Manim's interface to LaTeX for, e.g., rendering
+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.
+
+For MacOS, the recommended LaTeX distribution is
+`MacTeX <http://www.tug.org/mactex/>`__. You can install it by following
+the instructions from the link, or alternatively also via Homebrew by
+running:
+
+.. code-block:: bash
+
+ brew install --cask mactex
+
+.. warning::
+
+ MacTeX is a *full* LaTeX distribution and will require more than 4GB of
+ disk space. If this is an issue for you, consider installing a smaller
+ distribution like
+ `BasicTeX <http://www.tug.org/mactex/morepackages.html>`__.
+
+Should you choose to work with some partial TeX distribution, the full list
+of LaTeX packages which Manim interacts with in some way (a subset might
+be sufficient for your particular application) is::
+
+ amsmath babel-english cbfonts-fd cm-super ctex doublestroke dvisvgm everysel
+ fontspec frcursive fundus-calligra gnu-freefont jknapltx latex-bin
+ mathastext microtype ms physics preview ragged2e relsize rsfs
+ setspace standalone tipa wasy wasysym xcolor xetex xkeyval
+
+
+Working with Manim
+------------------
+
+At this point, you should have a working installation of Manim. Head
+over to our :doc:`Quickstart Tutorial <../tutorials/quickstart>` to learn
+how to make your own *Manimations*!
diff --git a/docs/source/installation/win.rst b/docs/source/installation/win.rst
deleted file mode 100644
index bcd447912..000000000
--- a/docs/source/installation/win.rst
+++ /dev/null
@@ -1,135 +0,0 @@
-Windows
-=======
-
-There are two simple ways to download manim's dependencies, using the popular package
-managers `Chocolatey <https://chocolatey.org/install>`__ and `Scoop <https://scoop.sh>`__
-
-.. _choco:
-
-Installing using Chocolatey
-***************************
-
-First, you need to install Chocolatey, which is a package manager for Windows
-systems. Please refer to `this link <https://chocolatey.org/install>`__ for
-instructions.
-
-You can install manim very easily using chocolatey, by typing the following command.
-
-.. code-block:: powershell
-
- choco install manimce
-
-
-And then you can skip all the other steps and move to installing
-:ref:`latex-installation`. Please see the :doc:`troubleshooting` section for
-details about OSError.
-
-FFmpeg installation
--------------------
-
-1. To install ``ffmpeg`` and add it to your PATH, install `Chocolatey
- <https://chocolatey.org/>`__ and run ``choco install ffmpeg``.
-
-2. You can check if you did it right by running ``refreshenv`` to update your
- environment variable and running ``ffmpeg``.
-
-
-.. _latex-installation:
-
-LaTeX Installation
-------------------
-You can install latex by either of the two methods below. MiKTex is very large
-(2 GB) while ManimLaTeX is small (500Mb).
-
-Using a custom distribution for Manim based on Texlive (recommended for beginners)
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-This is the smallest latex distribution just enough to run Manim. Extra latex
-packages for fonts can be installed using ``tlmgr``.
-See https://www.tug.org/texlive/tlmgr.html for more information.
-
-1. Install chocolatey if you haven't already.
-
-2. Run the following command
-
- .. code-block:: powershell
-
- choco install manim-latex
-
-3. Finally, check whether it installed properly by running an example scene.
-
-Using MiKTex
-++++++++++++
-1. Download the MiKTex installer from `this page
- <https://miktex.org/download>`__ and execute it.
-
- .. image:: ../_static/windows_miktex.png
- :align: center
- :width: 500px
- :alt: windows latex download page
-
-2. You can check if you did it right by running ``refreshenv`` to update your
- environment variable and running ``latex``.
-
-.. _scoop:
-
-Installing using Scoop
-**********************
-
-First, you need to install Scoop, which is a command-line installer for Windows
-systems. Please refer to `this link
-<https://scoop-docs.now.sh/docs/getting-started/Quick-Start.html>`__ for
-instructions.
-
-While a manifest for manim doesn't currently exist, it is sufficient to install
-the dependencies via scoop and manim itself via ``pip``.
-
-After installing Scoop, add these "buckets" as we'll need to install things from
-them later:
-
-.. code-block:: powershell
-
- scoop bucket add extras
- scoop bucket add r-bucket https://github.com/cderv/r-bucket.git
-
-FFmpeg installation
--------------------
-1. Run ``scoop install ffmpeg``
-2. Check whether ffmpeg has been properly installed by running ``ffmpeg``.
-
-LaTeX Installation
-------------------
-There are two ways of installing a LaTeX distribution that will be covered here:
-
-1. using MikTeX (approx. 2GB, takes a while to install, but provides "on-the-fly"
-package installation, recommended for beginners)
-
-2. using TinyTeX (approx. 500MB, installs quickly, but you have to install the required
-packages manually)
-
-Using Miktex
-++++++++++++
-Run ``scoop install latex`` and wait for the installer to complete its work. Most
-packages required by manim should be installed, but if some aren't you'll get a
-popup to install them while rendering.
-
-Using TinyTeX
-+++++++++++++
-Run ``scoop install tinytex`` and wait for the install to finish.
-Now run the following command to install all necessary packages for using manim:
-
-.. code-block:: powershell
-
- tlmgr install standalone everysel preview doublestroke ms setspace rsfs relsize ragged2e
- fundus-calligra microtype wasysym physics dvisvgm jknapltx wasy cm-super babel-english
- gnu-freefont mathastext cbfonts-fd
-
-You can check whether they were installed properly by rendering an example scene
-that uses :class:`~.Tex` or :class:`~.MathTex`.
-
-
-Certifying a clean install
-**************************
-
-After making sure you have a clean install following the instructions for each
-dependency above, you can go back to :ref:`installing-manim`.
diff --git a/docs/source/installation/windows.rst b/docs/source/installation/windows.rst
new file mode 100644
index 000000000..fae7a0e71
--- /dev/null
+++ b/docs/source/installation/windows.rst
@@ -0,0 +1,147 @@
+Windows
+=======
+
+The easiest way of installing Manim and its dependencies is by using a
+package manager like `Chocolatey <https://chocolatey.org/>`__
+or `Scoop <https://scoop.sh>`__. If you are not afraid of editing
+your System's ``PATH``, a manual installation is also possible.
+In fact, if you already have an existing Python
+installation (3.7 or newer), it might be the easiest way to get
+everything up and running.
+
+If you choose to use one of the package managers, please follow
+their installation instructions
+(`for Chocolatey <https://chocolatey.org/install#install-step2>`__,
+`for Scoop <https://scoop-docs.now.sh/docs/getting-started/Quick-Start.html>`__)
+to make one of them available on your system.
+
+
+Required Dependencies
+---------------------
+
+Manim requires a recent version of Python (3.7 or above) and ``ffmpeg``
+in order to work.
+
+Chocolatey
+**********
+
+Manim can be installed via Chocolatey simply by running:
+
+.. code-block:: powershell
+
+ choco install manimce
+
+That's it, no further steps required. You can continue with installing
+the :ref:`optional dependencies <win-optional-dependencies>` below.
+
+Scoop
+*****
+
+While there is no recipe for installing Manim with Scoop directly,
+you can install all requirements by running:
+
+.. code-block:: powershell
+
+ scoop install python ffmpeg
+
+and then Manim can be installed by running:
+
+.. code-block:: powershell
+
+ python -m pip install manim
+
+Manim should now be installed on your system. Continue reading
+the :ref:`optional dependencies <win-optional-dependencies>` section
+below.
+
+Manual Installation
+*******************
+
+As mentioned above, Manim needs a reasonably recent version of
+Python 3 (3.7 or above) and FFmpeg.
+
+**Python:** Head over to https://www.python.org, download an installer
+for Python 3.7 (or newer), and follow its instructions to get Python
+installed on your system.
+
+.. note::
+
+ We have received reports of problems caused by using the version of
+ Python that can be installed from the Windows Store. At this point,
+ we recommend staying away from the Windows Store version. Instead,
+ install Python directly from the
+ `official website <https://www.python.org>`__.
+
+**FFmpeg:** In order to install FFmpeg, you can get a
+pre-compiled and ready-to-use version from one of the resources
+linked at https://ffmpeg.org/download.html#build-windows, such as
+`the version available here
+<https://www.gyan.dev/ffmpeg/builds/ffmpeg-release-essentials.7z>`__
+(recommended), or if you know exactly what you are doing
+you can alternatively get the source code
+from https://ffmpeg.org/download.html and compile it yourself.
+
+
+After downloading the pre-compiled archive,
+`unzip it <https://www.7-zip.org>`__ and, if you like, move the
+extracted directory to some more permanent place (e.g.,
+``C:\Program Files\``). Next, edit the ``PATH`` environment variable:
+first, visit ``Control Panel`` > ``System`` > ``System settings`` >
+``Environment Variables``, then add the full path to the ``bin``
+directory inside of the (moved) ffmpeg directory to the
+``PATH`` variable. Finally, save your changes and exit.
+
+If you now open a new command line prompt (or PowerShell) and
+run ``ffmpeg``, the command should be recognized.
+
+At this point, you have all the required dependencies and can now
+install Manim via
+
+.. code-block:: powershell
+
+ python -m pip install manim
+
+
+.. _win-optional-dependencies:
+
+Optional Dependencies
+---------------------
+
+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.
+
+For Windows, the recommended LaTeX distribution is
+`MiKTeX <https://miktex.org/download>`__. You can install it by using the
+installer from the linked MiKTeX site, or by using the package manager
+of your choice (Chocolatey: ``choco install miktex.install``,
+Scoop: ``scoop install latex``).
+
+If you are concerned about disk space, there are some alternative,
+smaller distributions of LaTeX like
+`TinyTeX <https://yihui.org/tinytex/>`__ (Chocolatey: ``choco install tinytex``,
+Scoop: first ``scoop bucket add r-bucket https://github.com/cderv/r-bucket.git``,
+then ``scoop install tinytex``). In this case, you will have to manage the
+LaTeX packages installed on your system yourself via ``tlmgr``. Therefore we only
+recommend this option if you know what you are doing. The full list
+of LaTeX packages which Manim interacts with in some way (a subset might
+be sufficient for your particular application) is::
+
+ amsmath babel-english cbfonts-fd cm-super ctex doublestroke dvisvgm everysel
+ fontspec frcursive fundus-calligra gnu-freefont jknapltx latex-bin
+ mathastext microtype ms physics preview ragged2e relsize rsfs
+ setspace standalone tipa wasy wasysym xcolor xetex xkeyval
+
+.. note::
+
+ For Chocolatey there is a dedicated ``manim-latex`` package providing a
+ small LaTeX distribution based on TinyTeX which contains these packages;
+ if you use Chocolatey you can get it with ``choco install manim-latex``.
+
+
+Working with Manim
+------------------
+
+At this point, you should have a working installation of Manim, head
+over to our :doc:`Quickstart Tutorial <../tutorials/quickstart>` to learn
+how to make your own *Manimations*!
diff --git a/docs/source/installation/plugins.rst b/docs/source/plugins.rst
similarity index 100%
rename from docs/source/installation/plugins.rst
rename to docs/source/plugins.rst
diff --git a/docs/source/reference_index/scenes.rst b/docs/source/reference_index/scenes.rst
index 5ac41a897..dda4aff79 100644
--- a/docs/source/reference_index/scenes.rst
+++ b/docs/source/reference_index/scenes.rst
@@ -6,7 +6,6 @@ Inheritance Graph
-----------------
.. inheritance-diagram::
- manim.scene.graph_scene
manim.scene.moving_camera_scene
manim.scene.reconfigurable_scene
manim.scene.sample_space_scene
@@ -27,7 +26,6 @@ Module Index
.. autosummary::
:toctree: ../reference
- ~scene.graph_scene
~scene.moving_camera_scene
~scene.reconfigurable_scene
~scene.sample_space_scene
diff --git a/docs/source/tutorials/using_text.rst b/docs/source/tutorials/using_text.rst
index fac7c91ae..51be2cab8 100644
--- a/docs/source/tutorials/using_text.rst
+++ b/docs/source/tutorials/using_text.rst
@@ -110,6 +110,8 @@ Weight specifies the boldness of a font. You can see a list of weights in
g += Text(weight.name, weight=weight.name, font="Open Sans")
self.add(g.arrange(DOWN).scale(0.5))
+.. _using-colors:
+
Using Colors
------------
@@ -165,7 +167,8 @@ be an iterable of any length:
self.add(t)
You can also use :attr:`~.Text.t2g` for gradients with specific
-characters of the text. It shares a similar syntax to :ref:`Using Colors`:
+characters of the text. It shares a similar syntax to :ref:`the
+interface for colors <using-colors>`:
.. manim:: t2gExample
:save_last_frame:
diff --git a/manim/utils/space_ops.py b/manim/utils/space_ops.py
index 38dd775c6..a3aeb68f6 100644
--- a/manim/utils/space_ops.py
+++ b/manim/utils/space_ops.py
@@ -57,7 +57,7 @@ def quaternion_mult(
) -> Union[np.ndarray, List[Union[float, np.ndarray]]]:
"""Gets the Hamilton product of the quaternions provided.
For more information, check `this Wikipedia page
- <https://en.wikipedia.org/wiki/Quaternion>`_.
+ <https://en.wikipedia.org/wiki/Quaternion>`__.
Returns
-------
@@ -99,7 +99,7 @@ def quaternion_from_angle_axis(
) -> List[float]:
"""Gets a quaternion from an angle and an axis.
For more information, check `this Wikipedia page
- <https://en.wikipedia.org/wiki/Conversion_between_quaternions_and_Euler_angles>`_.
+ <https://en.wikipedia.org/wiki/Conversion_between_quaternions_and_Euler_angles>`__.
Parameters
----------