Improved CLI help page styling (#1975)

* First draft of cloup/click update

* Added some customizability via cfg files

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

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

* Fixed test_command epilogs

* Adjusted logic for overriding theme

* Update main help page, no_args_is_help, and documentation

* Removed help shorthand '-h'

* Apply suggestions from code review

Co-authored-by: Benjamin Hackl <[email protected]>

* Update poetry lock again, update DefaultGroup snippet

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Benjamin Hackl <[email protected]>
Co-authored-by: Naveen M K <[email protected]>

Author: 4 people

docs/source/tutorials/configuration.rst

@@ -363,3 +363,41 @@ A list of all config options
    'upto_animation_number', 'use_opengl_renderer', 'verbosity', 'video_dir',
    'window_position', 'window_monitor', 'window_size', 'write_all', 'write_to_movie',
    'enable_wireframe', 'force_window']
+
+
+Accessing CLI command options
+*****************************
+
+Entering ``manim``, or ``manim --help``, will open the main help page.
+
+.. code::
+
+   Usage: manim [OPTIONS] COMMAND [ARGS]...
+
+     Animation engine for explanatory math videos.
+
+   Options:
+     --version  Show version and exit.
+     --help     Show this message and exit.
+
+   Commands:
+     cfg      Manages Manim configuration files.
+     init     Sets up a new project in current working directory with default
+              settings.
+
+              It copies files from templates directory and pastes them in the
+              current working dir.
+     new      Create a new project or insert a new scene.
+     plugins  Manages Manim plugins.
+     render   Render SCENE(S) from the input FILE.
+
+   See 'manim <command>' to read about a specific subcommand.
+
+   Made with <3 by Manim Community developers.
+
+Each of the subcommands has its own help page which can be accessed similarly:
+
+.. code::
+
+   manim render
+   manim render --help

manim/__main__.py

@@ -3,10 +3,11 @@
 import sys
 
 import click
-from click_default_group import DefaultGroup
+import cloup
 
-from . import __version__, console
+from . import __version__, cli_ctx_settings, console
 from .cli.cfg.group import cfg
+from .cli.default_group import DefaultGroup
 from .cli.init.commands import init
 from .cli.new.group import new
 from .cli.plugins.commands import plugins
@@ -22,12 +23,13 @@ def exit_early(ctx, param, value):
 console.print(f"Manim Community [green]v{__version__}[/green]\n")
 
 
-@click.group(
+@cloup.group(
+    context_settings=cli_ctx_settings,
     cls=DefaultGroup,
     default="render",
     no_args_is_help=True,
-    help="Animation engine for explanatory math videos",
-    epilog=EPILOG,
+    help="Animation engine for explanatory math videos.",
+    epilog="See 'manim <command>' to read about a specific subcommand.\n\n" + EPILOG,
 )
 @click.option(
     "--version",

manim/_config/__init__.py

@@ -5,6 +5,7 @@
 import logging
 from contextlib import _GeneratorContextManager, contextmanager
 
+from .cli_colors import parse_cli_ctx
 from .logger_utils import make_logger
 from .utils import ManimConfig, ManimFrame, make_config_parser
 
@@ -15,6 +16,7 @@
     "config",
     "frame",
     "tempconfig",
+    "cli_ctx_settings",
 ]
 
 parser = make_config_parser()
@@ -28,6 +30,7 @@
     parser["logger"],
     parser["CLI"]["verbosity"],
 )
+cli_ctx_settings = parse_cli_ctx(parser["CLI_CTX"])
 # TODO: temporary to have a clean terminal output when working with PIL or matplotlib
 logging.getLogger("PIL").setLevel(logging.INFO)
 logging.getLogger("matplotlib").setLevel(logging.INFO)

manim/_config/cli_colors.py

@@ -0,0 +1,50 @@
+import configparser
+
+from cloup import Context, HelpFormatter, HelpTheme, Style
+
+
+def parse_cli_ctx(parser: configparser.ConfigParser) -> Context:
+    formatter_settings = {
+        "indent_increment": int(parser["indent_increment"]),
+        "width": int(parser["width"]),
+        "col1_max_width": int(parser["col1_max_width"]),
+        "col2_min_width": int(parser["col2_min_width"]),
+        "col_spacing": int(parser["col_spacing"]),
+        "row_sep": parser["row_sep"] if parser["row_sep"] else None,
+    }
+    theme_settings = {}
+    theme_keys = {
+        "command_help",
+        "invoked_command",
+        "heading",
+        "constraint",
+        "section_help",
+        "col1",
+        "col2",
+        "epilog",
+    }
+    for k, v in parser.items():
+        if k in theme_keys and v:
+            theme_settings.update({k: Style(v)})
+
+    formatter = {}
+    theme = parser["theme"] if parser["theme"] else None
+    if theme is None:
+        formatter = HelpFormatter().settings(
+            theme=HelpTheme(**theme_settings), **formatter_settings
+        )
+    elif theme.lower() == "dark":
+        formatter = HelpFormatter().settings(
+            theme=HelpTheme.dark().with_(**theme_settings), **formatter_settings
+        )
+    elif theme.lower() == "light":
+        formatter = HelpFormatter().settings(
+            theme=HelpTheme.light().with_(**theme_settings), **formatter_settings
+        )
+
+    return Context.settings(
+        align_option_groups=parser["align_option_groups"].lower() == "true",
+        align_sections=parser["align_sections"].lower() == "true",
+        show_constraints=True,
+        formatter_settings=formatter,
+    )

manim/_config/default.cfg

@@ -159,6 +159,36 @@ tex_template =
 # manim will load that plugin if it specified here.
 plugins =
 
+# CLI Context/Formatter
+# Visit the cloup documentation to understand the formatting options available:
+# https://cloup.readthedocs.io/en/latest/index.html#a-simple-example
+[CLI_CTX]
+# CTX settings
+align_option_groups = True
+align_sections = True
+show_constraints = True
+
+# Formatter settings
+indent_increment = 2
+width = 80
+col1_max_width = 30
+col2_min_width = 35
+col_spacing = 2
+row_sep =
+
+# Dark/Light, or leave empty
+theme =
+
+# Theme Settings - The following options override the theme colors.
+command_help =
+invoked_command =
+heading =
+constraint =
+section_help =
+col1 =
+col2 =
+epilog =
+
 # Overrides the default output folders, NOT the output file names.  Note that
 # if the custom_folders flag is present, the Tex and text files will not be put
 # under media_dir, as is the default.

manim/cli/cfg/group.py

@@ -11,12 +11,13 @@
 from ast import literal_eval
 
 import click
+import cloup
 from rich.errors import StyleSyntaxError
 from rich.style import Style
 
-from ... import console
+from ... import cli_ctx_settings, console
 from ..._config.utils import config_file_paths, make_config_parser
-from ...constants import CONTEXT_SETTINGS, EPILOG
+from ...constants import EPILOG
 from ...utils.file_ops import guarantee_existence, open_file
 
 RICH_COLOUR_INSTRUCTIONS: str = """
@@ -114,8 +115,8 @@ def replace_keys(default: dict) -> dict:
     return default
 
 
-@click.group(
-    context_settings=CONTEXT_SETTINGS,
+@cloup.group(
+    context_settings=cli_ctx_settings,
     invoke_without_command=True,
     no_args_is_help=True,
     epilog=EPILOG,
@@ -127,7 +128,7 @@ def cfg(ctx):
     pass
 
 
-@cfg.command(context_settings=CONTEXT_SETTINGS, no_args_is_help=True)
+@cfg.command(context_settings=cli_ctx_settings, no_args_is_help=True)
 @click.option(
     "-l",
     "--level",
@@ -237,7 +238,7 @@ def write(level: str = None, openfile: bool = False) -> None:
         open_file(cfg_file_path)
 
 
-@cfg.command(context_settings=CONTEXT_SETTINGS)
+@cfg.command(context_settings=cli_ctx_settings)
 def show():
     parser = make_config_parser()
     rich_non_style_entries = [a.replace(".", "_") for a in RICH_NON_STYLE_ENTRIES]
@@ -255,7 +256,7 @@ def show():
         console.print("\n")
 
 
-@cfg.command(context_settings=CONTEXT_SETTINGS)
+@cfg.command(context_settings=cli_ctx_settings)
 @click.option("-d", "--directory", default=os.getcwd())
 @click.pass_context
 def export(ctx, directory):

manim/cli/default_group.py

@@ -0,0 +1,67 @@
+"""DefaultGroup allows a subcommand to act as the main command
+
+In particular, this class is what allows ``manim`` to act as ``manim render``.
+"""
+import cloup
+
+from .. import logger
+
+__all__ = ["DefaultGroup"]
+
+
+class DefaultGroup(cloup.Group):
+    """Invokes a subcommand marked with ``default=True`` if any subcommand not
+    chosen.
+    """
+
+    def __init__(self, *args, **kwargs):
+        # To resolve as the default command.
+        if not kwargs.get("ignore_unknown_options", True):
+            raise ValueError("Default group accepts unknown options")
+        self.ignore_unknown_options = True
+        self.default_cmd_name = kwargs.pop("default", None)
+        self.default_if_no_args = kwargs.pop("default_if_no_args", False)
+        super().__init__(*args, **kwargs)
+
+    def set_default_command(self, command):
+        """Sets a command function as the default command."""
+        cmd_name = command.name
+        self.add_command(command)
+        self.default_cmd_name = cmd_name
+
+    def parse_args(self, ctx, args):
+        if not args and self.default_if_no_args:
+            args.insert(0, self.default_cmd_name)
+        return super().parse_args(ctx, args)
+
+    def get_command(self, ctx, cmd_name):
+        if cmd_name not in self.commands:
+            # No command name matched.
+            ctx.arg0 = cmd_name
+            cmd_name = self.default_cmd_name
+        return super().get_command(ctx, cmd_name)
+
+    def resolve_command(self, ctx, args):
+        base = super()
+        cmd_name, cmd, args = base.resolve_command(ctx, args)
+        if hasattr(ctx, "arg0"):
+            args.insert(0, ctx.arg0)
+            cmd_name = cmd.name
+        return cmd_name, cmd, args
+
+    def command(self, *args, **kwargs):
+        default = kwargs.pop("default", False)
+        decorator = super().command(*args, **kwargs)
+        if not default:
+            return decorator
+        logger.log(
+            "Use default param of DefaultGroup or " "set_default_command() instead",
+            DeprecationWarning,
+        )
+
+        def _decorator(f):
+            cmd = decorator(f)
+            self.set_default_command(cmd)
+            return cmd
+
+        return _decorator

manim/cli/init/commands.py

@@ -9,13 +9,13 @@
 
 from pathlib import Path
 
-import click
+import cloup
 
 from ...constants import CONTEXT_SETTINGS, EPILOG
 from ...utils.file_ops import copy_template_files
 
 
-@click.command(
+@cloup.command(
     context_settings=CONTEXT_SETTINGS,
     epilog=EPILOG,
     short_help="""Sets up a new project in current working directory with default settings.\n

manim/cli/new/group.py

@@ -4,6 +4,7 @@
 from pathlib import Path
 
 import click
+import cloup
 
 from ... import console
 from ...constants import CONTEXT_SETTINGS, EPILOG, QUALITIES
@@ -70,12 +71,12 @@ def update_cfg(cfg_dict, project_cfg_path):
         config.write(conf)
 
 
-@click.command(
+@cloup.command(
     context_settings=CONTEXT_SETTINGS,
     epilog=EPILOG,
 )
-@click.argument("project_name", type=Path, required=False)
-@click.option(
+@cloup.argument("project_name", type=Path, required=False)
+@cloup.option(
     "-d",
     "--default",
     "default_settings",
@@ -127,13 +128,13 @@ def project(default_settings, **args):
             update_cfg(CFG_DEFAULTS, new_cfg_path)
 
 
-@click.command(
+@cloup.command(
     context_settings=CONTEXT_SETTINGS,
     no_args_is_help=True,
     epilog=EPILOG,
 )
-@click.argument("scene_name", type=str, required=True)
-@click.argument("file_name", type=str, required=False)
+@cloup.argument("scene_name", type=str, required=True)
+@cloup.argument("file_name", type=str, required=False)
 def scene(**args):
     """Inserts a SCENE to an existing FILE or creates a new FILE.
 
@@ -174,14 +175,14 @@ def scene(**args):
             f.write("\n\n\n" + scene)
 
 
-@click.group(
+@cloup.group(
     context_settings=CONTEXT_SETTINGS,
     invoke_without_command=True,
     no_args_is_help=True,
     epilog=EPILOG,
     help="Create a new project or insert a new scene.",
 )
-@click.pass_context
+@cloup.pass_context
 def new(ctx):
     pass