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.txtindex c9356a728..3220975d3 100644--- a/docs/rtd-requirements.txt+++ b/docs/rtd-requirements.txt@@ -1 +1,2 @@jupyterlab+sphinxcontrib-programoutputdiff --git a/docs/source/conf.py b/docs/source/conf.pyindex 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 directivediff --git a/docs/source/tutorials/configuration.rst b/docs/source/tutorials/configuration.rstindex 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 timeof command invocation via `command-line arguments`_, or at the time the libraryis 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 --helpThe 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 involveusing many flags at the same time. This may become a nuisance if you mustexecute 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, manimcan also be configured using a configuration file. A configuration file is afile 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, manimdoes 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 = Truebackground_color = WHITE-Config files are read with the standard python library ``configparser``. In+Config files are parsed with the standard python library ``configparser``. Inparticular, 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 --helpdiff --git a/poetry.lock b/poetry.lockindex 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.tomlindex 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"