Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Made improvements to the :doc:`configuration` tutorial (#2414)

Darylgoldenccfea0ff4aed
diff --git a/docs/rtd-requirements.txt b/docs/rtd-requirements.txt
index c9356a728..3220975d3 100644
--- a/docs/rtd-requirements.txt
+++ b/docs/rtd-requirements.txt
@@ -1 +1,2 @@
jupyterlab
+sphinxcontrib-programoutput
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 0ddc6722e..7342756d6 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -45,6 +45,7 @@ extensions = [
"manim.utils.docbuild.manim_directive",
"sphinx.ext.graphviz",
"sphinx.ext.inheritance_diagram",
+ "sphinxcontrib.programoutput",
]
# Automatically generate stub pages when using the .. autosummary directive
diff --git a/docs/source/tutorials/configuration.rst b/docs/source/tutorials/configuration.rst
index 3edfe51ac..be219b1bc 100644
--- a/docs/source/tutorials/configuration.rst
+++ b/docs/source/tutorials/configuration.rst
@@ -8,6 +8,68 @@ can be configured programmatically via `the ManimConfig class`_, at the time
of command invocation via `command-line arguments`_, or at the time the library
is first imported via `the config files`_.
+The most common, simplest and recommended way to set the configure Manim is
+via the command-line interface (CLI), which is described directly below.
+
+Command-line arguments
+**********************
+
+By far the most commonly used command in the CLI is the ``render`` command,
+which is used to render scene(s) to an output file.
+It is used with the following arguments:
+
+.. program-output:: manim render --help
+ :ellipsis: 9
+
+However, since manim defaults to the :code:`render` command whenever no command
+is specified, the following form is far more common and can be used instead:
+
+.. code-block:: bash
+
+ manim [OPTIONS] FILE [SCENES]
+
+An example of using the above form is:
+
+.. code-block:: bash
+
+ manim -qm file.py SceneOne
+
+This asks manim to search for a Scene class called :code:`SceneOne` inside the
+file ``file.py`` and render it with medium quality (specified by the ``-qm`` flag).
+
+Another frequently used flag is ``-p`` ("preview"), which makes manim
+open the rendered video after it's done rendering.
+
+.. note:: The ``-p`` flag does not change any properties of the global
+ ``config`` dict. The ``-p`` flag is only a command-line convenience.
+
+Advanced examples
+=================
+
+To render a scene in high quality, but only output the last frame of the scene
+instead of the whole video, you can execute
+
+.. code-block:: bash
+
+ manim -sqh <file.py> SceneName
+
+The following example specifies the output file name (with the :code:`-o`
+flag), renders only the first ten animations (:code:`-n` flag) with a white
+background (:code:`-c` flag), and saves the animation as a ``.gif`` instead of as a
+``.mp4`` file (``--format=gif`` flag). It uses the default quality and does not try to
+open the file after it is rendered.
+
+.. code-block:: bash
+
+ manim -o myscene --format=gif -n 0,10 -c WHITE <file.py> SceneName
+
+A list of all CLI flags
+========================
+
+.. command-output:: manim --help
+.. command-output:: manim render --help
+.. command-output:: manim cfg --help
+.. command-output:: manim plugins --help
The ManimConfig class
*********************
@@ -74,70 +136,18 @@ rendered in our documentation with a reference frame.
self.add(Text(str(pixel_height)).next_to(d2, RIGHT))
-Command-line arguments
-**********************
-
-Usually, manim is run from the command-line by executing
-
-.. code-block:: bash
-
- manim <file.py> SceneName
-
-This asks manim to search for a Scene class called :code:`SceneName` inside the
-file <file.py> and render it. One can also specify the render quality by using
-the flags :code:`-ql`, :code:`-qm`, :code:`-qh`, or :code:`-qk`, for low, medium,
-high, and 4k quality, respectively.
-
-.. code-block:: bash
-
- manim -ql <file.py> SceneName
-
-These flags set the values of the config options ``config.pixel_width``,
-``config.pixel_height``, ``config.frame_rate``, and ``config.quality``.
-
-Another frequent flag is ``-p`` ("preview"), which makes manim show the rendered video
-right after it's done rendering.
-
-.. note:: The ``-p`` flag does not change any properties of the global
- ``config`` dict. The ``-p`` flag is only a command-line convenience.
-
-Examples
-========
-
-To render a scene in high quality, but only output the last frame of the scene
-instead of the whole video, you can execute
-
-.. code-block:: bash
-
- manim -sqh <file.py> SceneName
-
-The following example specifies the output file name (with the :code:`-o`
-flag), renders only the first ten animations (:code:`-n` flag) with a white
-background (:code:`-c` flag), and saves the animation as a .gif instead of as a
-.mp4 file (:code:`-i` flag). It uses the default quality and does not try to
-open the file after it is rendered.
-
-.. code-block:: bash
-
- manim -o myscene -i -n 0,10 -c WHITE <file.py> SceneName
-
-.. tip:: There are many more command-line flags that manim accepts. All the
- possible flags are shown by executing ``manim render --help``. A complete list
- of CLI flags is at the end of this document.
-
-
The config files
****************
As the last example shows, executing manim from the command-line may involve
using many flags at the same time. This may become a nuisance if you must
execute the same script many times in a short time period, for example when
-making small incremental tweaks to your scene script. For this purpose, manim
+making small incremental tweaks to your scene script. For this reason, manim
can also be configured using a configuration file. A configuration file is a
file ending with the suffix ``.cfg``.
-To use a configuration file when rendering your scene, you must create a file
-with name ``manim.cfg`` in the same directory as your scene code.
+To use a local configuration file when rendering your scene, you must create a
+file with name ``manim.cfg`` in the same directory as your scene code.
.. warning:: The config file **must** be named ``manim.cfg``. Currently, manim
does not support config files with any other name.
@@ -154,7 +164,7 @@ and serve the same purpose. Take for example the following config file.
save_as_gif = True
background_color = WHITE
-Config files are read with the standard python library ``configparser``. In
+Config files are parsed with the standard python library ``configparser``. In
particular, they will ignore any line that starts with a pound symbol ``#``.
Now, executing the following command
@@ -354,34 +364,3 @@ A list of all config options
'verbosity', 'video_dir', 'webgl_renderer_path', 'window_position',
'window_monitor', 'window_size', 'write_all', 'write_to_movie', 'enable_wireframe',
'force_window']
-
-
-A list of all CLI flags
-***********************
-
-.. code::
-
- manim --help
-
- Usage: manim [OPTIONS] COMMAND [ARGS]...
-
- Animation engine for explanatory math videos
-
- Options:
- --version Show the version and exit.
- --help Show this message and exit.
-
- Commands:
- render* Render SCENE(S) from the input FILE.
- cfg Manages Manim configuration files.
- plugins Manages Manim plugins.
-
- Made with <3 by Manim Community developers.
-
-Each of the subcommands has its own help page which can be
-
-.. code::
-
- manim render --help
- manim cfg --help
- manim plugins --help
diff --git a/poetry.lock b/poetry.lock
index 50cf070b4..753baefc3 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -2021,6 +2021,17 @@ python-versions = ">=3.5"
[package.extras]
test = ["pytest", "flake8", "mypy"]
+[[package]]
+name = "sphinxcontrib-programoutput"
+version = "0.17"
+description = "Sphinx extension to include program output"
+category = "dev"
+optional = false
+python-versions = ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*"
+
+[package.dependencies]
+Sphinx = ">=1.7.0"
+
[[package]]
name = "sphinxcontrib-qthelp"
version = "1.0.3"
@@ -2329,7 +2340,8 @@ webgl_renderer = ["grpcio", "grpcio-tools"]
[metadata]
lock-version = "1.1"
python-versions = "^3.7"
-content-hash = "15ed817719b587bc4b4ce2e27b8b39606c264085b491de518d0d7a5e411eec33"
+content-hash = "be65502bab269c81976c6e4c5cba0f4e4751c53b5657b08ffb3fa29cd323ae0f"
+
[metadata.files]
alabaster = [
@@ -3907,6 +3919,10 @@ sphinxcontrib-jsmath = [
{file = "sphinxcontrib-jsmath-1.0.1.tar.gz", hash = "sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"},
{file = "sphinxcontrib_jsmath-1.0.1-py2.py3-none-any.whl", hash = "sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178"},
]
+sphinxcontrib-programoutput = [
+ {file = "sphinxcontrib-programoutput-0.17.tar.gz", hash = "sha256:300ee9b8caee8355d25cc74b4d1c7efd12e608d2ad165e3141d31e6fbc152b7f"},
+ {file = "sphinxcontrib_programoutput-0.17-py2.py3-none-any.whl", hash = "sha256:0ef1c1d9159dbe7103077748214305eb4e0138e861feb71c0c346afc5fe97f84"},
+]
sphinxcontrib-qthelp = [
{file = "sphinxcontrib-qthelp-1.0.3.tar.gz", hash = "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72"},
{file = "sphinxcontrib_qthelp-1.0.3-py2.py3-none-any.whl", hash = "sha256:bd9fc24bcb748a8d51fd4ecaade681350aa63009a347a8c14e637895444dfab6"},
diff --git a/pyproject.toml b/pyproject.toml
index 79d5349ad..b028a496c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -93,6 +93,7 @@ flake8-rst-docstrings = "^0.2.3"
flake8-pytest-style = "^1.5.0"
flake8-simplify = "^0.14.1"
flake8-comprehensions = "^3.7.0"
+sphinxcontrib-programoutput = "^0.17"
data-science-types = "^0.2.23"