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

* Attempt to use CI to update translations

* try again

* runs on ubuntu latest

* Try to fix

* again

* try to use PR branch

* that didn't work

* will this work?

* Revert "will this work?"

This reverts commit 1e6543a.

* Try a different action

* fix attempt

* another attempt

* Revert "another attempt"

This reverts commit 8965000.

* try again

* automatically generate list of all flags

* remove unrelated change

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* specify dep

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Update tutorial

Move CLI stuff to the top since it's the most important, slight rewrite, some copyediting

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* slight rephrasing

* make underline long enough

* Revert "Merge branch 'main' into command-output"

This reverts commit e6a9d45, reversing
changes made to 3f0137a.

* Revert "Revert "Merge branch 'main' into command-output""

This reverts commit c823c6e.

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: Darylgolden

docs/rtd-requirements.txt

@@ -1 +1,2 @@
 jupyterlab
+sphinxcontrib-programoutput

docs/source/conf.py

@@ -45,6 +45,7 @@
     "manim.utils.docbuild.manim_directive",
     "sphinx.ext.graphviz",
     "sphinx.ext.inheritance_diagram",
+    "sphinxcontrib.programoutput",
 ]
 
 # Automatically generate stub pages when using the .. autosummary directive

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

poetry.lock

@@ -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"