Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

1: make sphinx accept markdown files. 2: add a changelog stub file. 3: add a sample quickstart text that shows how to include .gif files.

leotrse1f97335b97d
diff --git a/docs/source/_static/quickstart/first_scene.gif b/docs/source/_static/quickstart/first_scene.gif
new file mode 100644
index 000000000..c23d42b29
Binary files /dev/null and b/docs/source/_static/quickstart/first_scene.gif differ
diff --git a/docs/source/_static/quickstart/first_scene_4k.gif b/docs/source/_static/quickstart/first_scene_4k.gif
new file mode 100644
index 000000000..4bde21aef
Binary files /dev/null and b/docs/source/_static/quickstart/first_scene_4k.gif differ
diff --git a/docs/source/_static/quickstart/second_scene.gif b/docs/source/_static/quickstart/second_scene.gif
new file mode 100644
index 000000000..abefa7e3e
Binary files /dev/null and b/docs/source/_static/quickstart/second_scene.gif differ
diff --git a/docs/source/tutorial.rst b/docs/source/changelog.rst
similarity index 52%
rename from docs/source/tutorial.rst
rename to docs/source/changelog.rst
index 769a1ddb2..e35dcd8ef 100644
--- a/docs/source/tutorial.rst
+++ b/docs/source/changelog.rst
@@ -1,4 +1,4 @@
-Tutorial
-========
+Changelog
+=========
This is a stub file.
diff --git a/docs/source/conf.py b/docs/source/conf.py
index ace00af18..25d20277a 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -30,6 +30,7 @@ author = 'The Manim Community Dev Team'
extensions = [
'sphinx.ext.autodoc',
'sphinx_rtd_theme',
+ 'recommonmark',
]
# Add any paths that contain templates here, relative to this directory.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 576cfffd1..7fb4115f3 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -24,6 +24,7 @@ information here will make it easier for newcomers to get started using
tutorial
configuration
reference
+ changelog
* :ref:`genindex`
* :ref:`modindex`
diff --git a/docs/source/quickstart.md b/docs/source/quickstart.md
new file mode 100644
index 000000000..223235ce5
--- /dev/null
+++ b/docs/source/quickstart.md
@@ -0,0 +1,116 @@
+# Quickstart
+
+This document will lead you step by step through the necessary procedure to get
+`manim` up and running as soon as possible.
+
+
+## Installation
+
+[INSTALLATION INSTRUCTIONS GO HERE]. Note: when this section is done, delete
+installation instructions from the GitHub repo README.
+
++ mention pip isntall
++ mention choco package
++ mention things about Cairo and LaTeX
+
+
+## Start a new project
+
+To start a new manim video project, all you need to do is choose a single
+folder where all of the files related to the video will reside. For this
+example, this folder will be called `project`,
+
+```
+project/
+```
+
+Every file containing code that produces a video with manim will be stored
+here, as well as `manim`'s output files and configuration files.
+
+
+## Your first Scene
+
+To produce your first scene, create a new file in your project folder
+
+```
+project/
+└─scene.py
+```
+
+and copy the following code in it
+
+```python
+from manim import *
+
+# all code must be contained inside the construct
+# method of a class that inherits from Scene
+class SquareToCircle(Scene):
+ def construct(self):
+ circle = Circle() # create a circle
+ circle.set_fill(PINK, opacity=0.5) # set the color and transparency
+ self.play(ShowCreation(circle)) # show the circle on screen
+```
+
+Then open your command line, navigate to your project directory, and execute
+the following command:
+
+```bash
+$ manim scene.py SquareToCircle -pl
+```
+
+After some output, `manim` should render the scene into a .mp4 file, and open
+that file with the default movie player application. You should see a video
+playing the following animation.
+
+![first scene output](_static/quickstart/first_scene.gif)
+
+If you see the video and it looks correct, congrats! You just wrote your first
+`manim` scene from scratch. If you get an error message instead, or if do not
+see a video, or if the video output does not look like this, it is likely that
+`manim` has not been installed correctly. Please refer to the Troubleshooting
+page for more information.
+
+## Some bells and whistles
+
+Our scene is a little basic, so let's add some bells and whistles. Modify the
+`scene.py` file to contain the following:
+
+```python
+from manim import *
+
+class SquareToCircle(Scene):
+ def construct(self):
+ circle = Circle() # create a circle
+ circle.set_fill(PINK, opacity=0.5) # set color and transparency
+
+ square = Square() # create a square
+ square.flip(RIGHT) # flip horizontally
+ square.rotate(-3 * TAU / 8) # rotate a certain amount
+
+ self.play(ShowCreation(square)) # animate the creation of the square
+ self.play(Transform(square, circle)) # interpolate the square into the circle
+ self.play(FadeOut(square)) # fade out animation
+```
+
+And render it using the following command:
+
+```bash
+$ manim scene.py SquareToCircle -pl
+```
+
+The output should look as follows.
+
+![second scene output](_static/quickstart/second_scene.gif)
+
+This example shows one of the most basic features of `manim`: the ability to
+implement complicated and perhaps mathematically-intensive animations (such as
+cleanly interpolating between two geometric shapes) in very few lines of code.
+
+
+## You're done!
+
+With a working installation of manim, and the bare basics under your belt, it
+is now time to start creating awesome mathematical animations. For a more
+extensive review of manim's features, as well as its configuration and other
+settings, see the Tutorial page. For a list of all available features, see the
+Reference page.
diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst
deleted file mode 100644
index 9f01c1734..000000000
--- a/docs/source/quickstart.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Quickstart
-==========
-
-This is a stub file.
diff --git a/docs/source/tutorial.md b/docs/source/tutorial.md
new file mode 100644
index 000000000..9105bef81
--- /dev/null
+++ b/docs/source/tutorial.md
@@ -0,0 +1,84 @@
+[NOTE:] this is some text I wrote that was originally meant to be part of the
+quickstart. However, after some thought I've decided that it's probably a bit
+too much for the quickstart, as the quickstart document is supposed to showcase
+the quickest way of getting up and running with manim. I've moved it here for
+now, but feel free to edit/delete/move this text elsewhere in the
+documentation.
+
+
+## A deeper look
+
+Let's dissect what just happened step by step. First, the following command
+
+```bash
+$ manim scene.py SquareToCircle -pl
+```
+
+executes `manim` on the file `scene.py`, which contains our animation code.
+Further, this command tells manim exactly which `Scene` to be rendered, in this
+case it is `SquareToCircle`. A single scene file may contain more than one
+scene. Next, the flag `-p` tells manim to play the scene once it's rendered,
+and the `-l` flag tells manim to render the scene in low quality.
+
+After the video is rendered, you will see that manim has generated some new
+files and the project folder will look as follows.
+
+```
+project/
+├─scene.py
+└─media
+ ├─videos
+ | └─scene
+ | └─480p15
+ | ├─SquareToCircle.mp4
+ | └─partial_movie_files
+ ├─text
+ └─Tex
+```
+
+There are quite a few new files. The main output is in
+`media/videos/scene/480p15/SquareToCircle.mp4`. By default, the `media` folder
+will contain all of manim's output files. The `media/videos` subfolder
+contains the rendered videos. Inside of it, you will find one folder for each
+different video quality. In our case, since we used the `-l` flag, the video
+was generated at 480p at 15 frames per second from the `scene.py` file.
+Therefore, the output can be found inside `media/videos/scene/480p15`. The
+additional folders `media/videos/scene/480p15/partial_movie_files` as well as
+`media/text` and `media/Tex` contain files that are used by manim internally.
+
+You can see how manim makes use of the generated folder structure by executing
+the following command,
+
+```bash
+$ manim scene.py SquareToCircle -pk
+```
+
+The `-l` flag (for low quality) has been replaced by the `-k` flag, for 4K
+quality. Manim will take considerably longer to render this file, and it will
+play it once it's done since we are using the `-p` flag. The output should
+look like this:
+
+![first scene output](_static/quickstart/first_scene_4k.gif)
+
+And the folder structure should look as follows.
+
+```
+project/
+├─scene.py
+└─media
+ ├─videos
+ | └─scene
+ | ├─480p15
+ | | ├─SquareToCircle.mp4
+ | | └─partial_movie_files
+ | └─2160p60
+ | ├─SquareToCircle.mp4
+ | └─partial_movie_files
+ ├─text
+ └─Tex
+```
+
+Manim has created a new folder `media/videos/2160p60`, which corresponds to the
+resolution and the 60 frames per second corresponding to 4k quality. Inside of
+it, you can find the new `SquareToCircle.mp4`, as well as the corresponding
+`partial_movie_files`.
diff --git a/requirements.txt b/requirements.txt
index 9c1176aee..931676c0f 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -9,5 +9,6 @@ pygments
pyreadline; sys_platform == 'win32'
rich>=4.2.1
sphinx-rtd-theme
+recommonmark>=0.5.0
# pytest (for development only)
# black (for development only)