A community-maintained Python framework for creating mathematical animations.
Documenting the config system (#303)
Leo Torres54854ccf2306
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 68e941e77..358a99733 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,4 +1,4 @@-# General Contribution Guidelines+# Contributing1. If code changes are being made, please include documentation **following the guidelines in the Wiki** (typings are also welcome, but we can probably do them for you, given the documentation).2. (For the maintainers of this repo) Label PRs appropriately.@@ -6,7 +6,7 @@4. Ensure compatibility with the latest changes in the repo.5. After you've made your changes, please test them out thoroughly. If the repository has any example code or code exclusively used for testing, please test your changes against those. If you have added new features, consider writing and contributing to a test for that feature to ensure it works properly.-## Contributing to the Manim Community Fork - General instructions+## General instructionsAs this is a Fork of [Manim by 3b1b](https://github.com/3b1b/manim), contributing can be a bit confusing. Because of that, here is a small guide on it.diff --git a/docs/source/conf.py b/docs/source/conf.pyindex 002fc21f2..31900a5d1 100644--- a/docs/source/conf.py+++ b/docs/source/conf.py@@ -32,9 +32,11 @@ extensions = ['sphinx_rtd_theme','recommonmark','sphinx.ext.napoleon',- 'sphinx.ext.autosummary'+ 'sphinx.ext.autosummary',+ 'sphinx.ext.doctest',]+# Automatically generate stub pages when using the .. autosummary directiveautosummary_generate = True# Add any paths that contain templates here, relative to this directory.@@ -56,4 +58,4 @@ html_theme = 'sphinx_rtd_theme'# Add any paths that contain custom static files (such as style sheets) here,# relative to this directory. They are copied after the builtin static files,# so a file named "default.css" will overwrite the builtin "default.css".-html_static_path = ['_static']+html_static_path = ['_static', 'readme-assets']diff --git a/docs/source/configuration.rst b/docs/source/configuration.rstdeleted file mode 100644index 1514c4260..000000000--- a/docs/source/configuration.rst+++ /dev/null@@ -1,4 +0,0 @@-Configuration-=============--This is a stub file.diff --git a/docs/source/contributing.md b/docs/source/contributing.mddeleted file mode 100644index d93f74f93..000000000--- a/docs/source/contributing.md+++ /dev/null@@ -1,3 +0,0 @@-# Contribution--https://github.com/ManimCommunity/manim\ No newline at end of filediff --git a/docs/source/contributing.md b/docs/source/contributing.mdnew file mode 120000index 000000000..f939e75f2--- /dev/null+++ b/docs/source/contributing.md@@ -0,0 +1 @@+../../CONTRIBUTING.md\ No newline at end of filediff --git a/docs/source/examples.md b/docs/source/examples.mddeleted file mode 100644index 9db287125..000000000--- a/docs/source/examples.md+++ /dev/null@@ -1,3 +0,0 @@-# Examples--Lots of manim examples\ No newline at end of filediff --git a/docs/source/installation/installation_arch.rst b/docs/source/installation/installation_arch.rstindex aae24327e..1ae324409 100644--- a/docs/source/installation/installation_arch.rst+++ b/docs/source/installation/installation_arch.rst@@ -1,2 +1,2 @@Arch/Manjaro-=====\ No newline at end of file+============diff --git a/docs/source/installation/installation_ubuntu.rst b/docs/source/installation/installation_ubuntu.rstindex 1be635da5..aa085f39d 100644--- a/docs/source/installation/installation_ubuntu.rst+++ b/docs/source/installation/installation_ubuntu.rst@@ -1,2 +1,2 @@Ubuntu/Debian-=====\ No newline at end of file+=============diff --git a/docs/source/installation/installation_win.rst b/docs/source/installation/installation_win.rstindex 1d374abe6..c863dc648 100644--- a/docs/source/installation/installation_win.rst+++ b/docs/source/installation/installation_win.rst@@ -1,2 +1,2 @@Windows-=====\ No newline at end of file+=======diff --git a/docs/source/readme-assets/pull-requests.PNG b/docs/source/readme-assets/pull-requests.PNGnew file mode 120000index 000000000..a1852462d--- /dev/null+++ b/docs/source/readme-assets/pull-requests.PNG@@ -0,0 +1 @@+../../../readme-assets/pull-requests.PNG\ No newline at end of filediff --git a/docs/source/reference.rst b/docs/source/reference.rstindex 7da14bf03..5efaa821a 100644--- a/docs/source/reference.rst+++ b/docs/source/reference.rst@@ -3,8 +3,8 @@ ReferenceThis reference manual details functions, modules, and objects included inManim, describing what they are and what they do. For learning how to use-Manim, see the :doc:`quickstart` and :doc:`tutorial` documents.-Want to see whats new? Here is the :doc:`changelog`+Manim, see :doc:`tutorials/tutorials_index`. For a list of changes since the+last release, see the :doc:`changelog`... currentmodule:: manimdiff --git a/docs/source/tutorials/configuration.rst b/docs/source/tutorials/configuration.rstnew file mode 100644index 000000000..c3eeb15dd--- /dev/null+++ b/docs/source/tutorials/configuration.rst@@ -0,0 +1,286 @@+Configuration+=============++Manim provides an extensive configuration system that allows it to adapt to+many different use cases. The easiest way to do this is through the use of+command line (or *CLI*) arguments.+++Command Line Arguments+**********************++Usually, manim is ran 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:`-l`, :code:`-m`, :code:`-e`, or :code:`-k`, for low, medium,+high, and 4k quality, respectively.++.. code-block:: bash++ $ manim <file.py> SceneName -l++Another frequent flag is :code:`-p`, which makes manim show the rendered video+right after it's done rendering.++There are in fact many more command line flags that manim accepts. All the+possible flags are shown by the following command.++.. code-block:: bash++ $ manim -h++The output looks as follows.++.. testcode::+ :hide:++ import subprocess+ result = subprocess.run(['manim', '-h'], stdout=subprocess.PIPE)+ print(result.stdout.decode('utf-8'))++.. testoutput::+ :options: -ELLIPSIS, +NORMALIZE_WHITESPACE++ usage: manim [-h] [-o OUTPUT_FILE] [-p] [-f] [--sound] [--leave_progress_bars]+ [-a] [-w] [-s] [-g] [-i] [--disable_caching] [--flush_cache]+ [--log_to_file] [-c BACKGROUND_COLOR]+ [--background_opacity BACKGROUND_OPACITY] [--media_dir MEDIA_DIR]+ [--log_dir LOG_DIR] [--tex_template TEX_TEMPLATE] [--dry_run]+ [-t] [-l] [-m] [-e] [-k] [-r RESOLUTION]+ [-n FROM_ANIMATION_NUMBER] [--config_file CONFIG_FILE]+ [-v {DEBUG,INFO,WARNING,ERROR,CRITICAL}]+ [--progress_bar True/False]+ {cfg} ... file [scene_names [scene_names ...]]++ Animation engine for explanatory math videos++ positional arguments:+ {cfg}+ file path to file holding the python code for the scene+ scene_names Name of the Scene class you want to see++ optional arguments:+ -h, --help show this help message and exit+ -o OUTPUT_FILE, --output_file OUTPUT_FILE+ Specify the name of the output file, if it should be+ different from the scene class name+ -p, --preview Automatically open the saved file once its done+ -f, --show_in_file_browser+ Show the output file in the File Browser+ --sound Play a success/failure sound+ --leave_progress_bars+ Leave progress bars displayed in terminal+ -a, --write_all Write all the scenes from a file+ -w, --write_to_movie Render the scene as a movie file (this is on by+ default)+ -s, --save_last_frame+ Save the last frame only (no movie file is generated)+ -g, --save_pngs Save each frame as a png+ -i, --save_as_gif Save the video as gif+ --disable_caching Disable caching (will generate partial-movie-files+ anyway)+ --flush_cache Remove all cached partial-movie-files+ --log_to_file Log terminal output to file+ -c BACKGROUND_COLOR, --background_color BACKGROUND_COLOR+ Specify background color+ --background_opacity BACKGROUND_OPACITY+ Specify background opacity+ --media_dir MEDIA_DIR+ Directory to store media (including video files)+ --log_dir LOG_DIR Directory to store log files+ --tex_template TEX_TEMPLATE+ Specify a custom TeX template file+ --dry_run Do a dry run (render scenes but generate no output+ files)+ -t, --transparent Render a scene with an alpha channel+ -l, --low_quality Render at low quality+ -m, --medium_quality Render at medium quality+ -e, --high_quality Render at high quality+ -k, --fourk_quality Render at 4K quality+ -r RESOLUTION, --resolution RESOLUTION+ Resolution, passed as "height,width". Overrides the+ -l, -m, -e, and -k flags, if present+ -n FROM_ANIMATION_NUMBER, --from_animation_number FROM_ANIMATION_NUMBER+ Start rendering at the specified animation index,+ instead of the first animation. If you pass in two+ comma separated values, e.g. '3,6', it will end the+ rendering at the second value+ --config_file CONFIG_FILE+ Specify the configuration file+ -v {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --verbosity {DEBUG,INFO,WARNING,ERROR,CRITICAL}+ Verbosity level. Also changes the ffmpeg log level+ unless the latter is specified in the config+ --progress_bar True/False+ Display the progress bar++ Made with <3 by the manim community devs++For example, 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 <file.py> SceneName -es++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 <file.py> SceneName -o myscene -i -n 0,10 -c WHITE++++The config files+****************++As the last example shows, executing manim from the command line may involve+using many flags at the same. This may become a nuisance if you must execute+the same file many times in a short time period, for example when making small+incremental tweaks to your scene script. For this purpose, manim can also be+configured using a configuration file.++To use a configuration file when rendering your scene, you must create a file+with name :code:`manim.cfg` in the same directory as your scene code.++.. warning:: The config file **must** be named :code:`manim.cfg`. Currently,+ manim does not support config files with any other name.++The config file must start with a section header, usually :code:`[CLI]`. The+configuration options under this header have the same name as the CLI flags,+and serve the same purpose. Take for example the following config file.++.. code-block::++ [CLI]+ output_file = myscene+ save_as_gif = True+ background_color = WHITE++Executing :code:`manim <file.py> SceneName` on a directory that contains this+config file is equivalent to executing++.. code-block:: bash++ $ manim <file.py> SceneName -o myscene -i -c WHITE++on a directory that does not contain a config file.++.. note:: The names of the configuration options admissible in config files are+ exactly the same as the **long names** of the corresponding command+ line flags. For example, the :code:`-c` and+ :code:`--background_color` flags are interchangeable, but the config+ file only accepts :code:`background_color` as an admissible option.++.. note:: Configuration options that do not have command line analogues will be+ ignored. For a list of all the command line flags, see `Command Line+ Arguments`_.++Manim will look for a :code:`manim.cfg` config file in the same directory as+the file being rendered, and **not** in the directory of execution. For+example,++.. code-block:: bash++ $ manim <file.py> path/to/SceneName -o myscene -i -c WHITE++will use the config file found in :code:`path/to/SceneName`, if any. It will+**not** use the config file found in the current working directory, even if it+exists. In this way, the user may keep different config files for different+scenes or projects, and execute them with the right configuration from anywhere+in the system.++.. note:: Config files will ignore any line that starts with a pound symbol+ :code:`#`.+++The user config file+********************++As explained in the previous section, a :code:`manim.cfg` config file only+affects the scene scripts in its same directory. However, the user may also+create a special config file that will apply to all scenes rendered by that+user. This is referred to as the **user-wide** config file, and it will apply+regardless of where manim is executed from, and regardless of where the scene+script is stored.++The user-wide config file lives in a special folder, depending on the operating+system.++* Windows: :code:`UserDirectory`/AppData/Roaming/Manim/manim.cfg+* MacOS: :code:`UserDirectory`/config/manim/manim.cfg+* Linux: :code:`UserDirectory`/config/manim/manim.cfg++Here, :code:`UserDirectory` is the user's home folder.+++.. note:: Config files that only apply to their own folder, explained in the+ previous section, are called **folder-wide** config files. A user+ may have many folder-wide config files, one per folder, but only one+ **user-wide** config file. Different users in the same computer may+ each have their own user-wide config file.++.. warning:: Do not store scene scripts in the same folder as the user-wide+ config file. In this case, the behavior is undefined.++Whenever you use manim from anywhere in the system, manim will look for a+user-wide config file and read its configuration.+++Cascading config files+**********************++What happens if you execute manim and it finds both a folder-wide config file+and a user-wide config file? Manim will read both files, but if they are+incompatible, **the folder-wide file takes precedence**.++For example, take the following user-wide config file++.. code-block::++ # user-wide+ [CLI]+ output_file = myscene+ save_as_gif = True+ background_color = WHITE++and the following folder-wide file++.. code-block::++ # folder-wide+ [CLI]+ save_as_gif = False++Then, executing :code:`manim <file.py> SceneName` will be equivalent to not+using any config files and executing++.. code-block:: bash++ manim <file.py> SceneName -o myscene -c WHITE++Any command line flags have precedence over any config file. For example,+using the previous two config files and executing :code:`manim <file.py>+SceneName -c RED` is equivalent to not using any config files and executing++.. code-block:: bash++ manim <file.py> SceneName -o myscene -c RED++To summarize, the order of precedence for configuration options is: *user-wide+config file < folder-wide config file < CLI flags*.+++.. note:: There is also a **library-wide** config file that determines manim's+ default behavior, and applies to every user of the library. It has+ the least precedence, and **the user should not try to modify it**.+ Developers should receive explicit confirmation from the core+ developer team before modifying it.diff --git a/docs/source/tutorials/tutorials_index.rst b/docs/source/tutorials/tutorials_index.rstindex d69c4b8d7..fe3f80dda 100644--- a/docs/source/tutorials/tutorials_index.rst+++ b/docs/source/tutorials/tutorials_index.rst@@ -6,4 +6,4 @@ Tutorialsquickstarta_deeper_look-+ configurationdiff --git a/manim/config.py b/manim/config.pyindex 57ad84420..1eb1188ae 100644--- a/manim/config.py+++ b/manim/config.py@@ -45,10 +45,10 @@ def _parse_config(config_parser, args):height, width = int(args.resolution), int(16 * height / 9)config["camera_config"].update({"pixel_height": height, "pixel_width": width})- # Handle the -c (--color) flag- if args.color is not None:+ # Handle the -c (--background_color) flag+ if args.background_color is not None:try:- background_color = colour.Color(args.color)+ background_color = colour.Color(args.background_color)except AttributeError as err:logger.warning("Please use a valid color.")logger.error(err)diff --git a/manim/default.cfg b/manim/default.cfgindex 5786bc2a1..a8361d350 100644--- a/manim/default.cfg+++ b/manim/default.cfg@@ -54,7 +54,7 @@ leave_progress_bars = False# --log_to_filelog_to_file = False-# -c, --color+# -c, --background_colorbackground_color = BLACK# --background_opacitydiff --git a/manim/utils/config_utils.py b/manim/utils/config_utils.pyindex 9d445fcc2..0248d4cca 100644--- a/manim/utils/config_utils.py+++ b/manim/utils/config_utils.py@@ -240,14 +240,14 @@ def _parse_cli(arg_list, input=True):"--write_to_movie",action="store_const",const=True,- help="Render the scene as a movie file",+ help="Render the scene as a movie file (this is on by default)",)parser.add_argument("-s","--save_last_frame",action="store_const",const=True,- help="Save the last frame (and do not save movie)",+ help="Save the last frame only (no movie file is generated)",)parser.add_argument("-g",@@ -267,48 +267,33 @@ def _parse_cli(arg_list, input=True):"--disable_caching",action="store_const",const=True,- help="Disable caching (will generate partial-movie-files anyway).",+ help="Disable caching (will generate partial-movie-files anyway)",)parser.add_argument("--flush_cache",action="store_const",const=True,- help="Remove all cached partial-movie-files.",+ help="Remove all cached partial-movie-files",)parser.add_argument("--log_to_file",action="store_const",const=True,- help="Log terminal output to file.",+ help="Log terminal output to file",)# The default value of the following is set in manim.cfgparser.add_argument(- "-c", "--color", help="Background color",+ "-c", "--background_color", help="Specify background color",)parser.add_argument(- "--background_opacity", help="Background opacity",+ "--background_opacity", help="Specify background opacity",)parser.add_argument(- "--media_dir", help="directory to write media",+ "--media_dir", help="Directory to store media (including video files)",)-parser.add_argument(- "--log_dir", help="directory to write log files to",- )-- # video_group = parser.add_mutually_exclusive_group()- # video_group.add_argument(- # "--video_dir",- # help="directory to write file tree for video",- # )- # parser.add_argument(- # "--tex_dir",- # help="directory to write tex",- # )- # parser.add_argument(- # "--text_dir",- # help="directory to write text",- # )+ "--log_dir", help="Directory to store log files",+ )parser.add_argument("--tex_template", help="Specify a custom TeX template file",)@@ -332,48 +317,39 @@ def _parse_cli(arg_list, input=True):"-t","--transparent",action="store_true",- help="Render to a movie file with an alpha channel",+ help="Render a scene with an alpha channel",)# The following are mutually exclusive and each overrides# FRAME_RATE, PIXEL_HEIGHT, and PIXEL_WIDTH,parser.add_argument(- "-l",- "--low_quality",- action="store_true",- help="Render at low quality (for fastest rendering)",+ "-l", "--low_quality", action="store_true", help="Render at low quality",)parser.add_argument(- "-m",- "--medium_quality",- action="store_true",- help="Render at medium quality (for much faster rendering)",+ "-m", "--medium_quality", action="store_true", help="Render at medium quality",)parser.add_argument(- "-e",- "--high_quality",- action="store_true",- help="Render at high quality (for slightly faster rendering)",+ "-e", "--high_quality", action="store_true", help="Render at high quality",)parser.add_argument(- "-k",- "--fourk_quality",- action="store_true",- help="Render at 4K quality (slower rendering)",+ "-k", "--fourk_quality", action="store_true", help="Render at 4K quality",)# This overrides any of the aboveparser.add_argument(- "-r", "--resolution", help='Resolution, passed as "height,width"',+ "-r",+ "--resolution",+ help='Resolution, passed as "height,width". '+ "Overrides the -l, -m, -e, and -k flags, if present",)# This sets FROM_ANIMATION_NUMBER and UPTO_ANIMATION_NUMBERparser.add_argument("-n","--from_animation_number",- help="Start rendering not from the first animation, but"- "from another, specified by its index. If you pass"- 'in two comma separated values, e.g. "3,6", it will end'+ help="Start rendering at the specified animation index, "+ "instead of the first animation. If you pass in two comma "+ "separated values, e.g. '3,6', it will end ""the rendering at the second value",)