Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# Help formatting and themes

## Formatting settings

The following formatting settings can be provided both at the context and at the command level:

- align_option_groups – whether to align option group sections (see here)

- align_sections – whether to align sections of subcommands; this is the analogous of `align_option_groups` for subcommand sections

- show_constraints – whether to include the “Constraints” section (see here)

- show_subcommand_aliases – whether to show aliases of subcommands in the `--help` output of a `Group` (see here)

- formatter_settings – a dictionary of parameters to forward to `HelpFormatter` (click on it for the full list). The following of this chapter is all about these.

Context-level settings propagate to subcommands, while command-level settings don’t.

Of course, command-level settings override context-level settings. In particular, the context-level and command-level `formatter_settings` are merged together, with command-level settings having higher priority.

### An example

Tip

In Cloup, you can use the static methods `Context.settings()` and `HelpFormatter.settings()` to create dictionaries without leaving your IDE to check the docs.

    from cloup import Context, command, group, HelpFormatter, HelpTheme

    CONTEXT_SETTINGS = Context.settings(
        # parameters of Command:
        align_option_groups=False,
        align_sections=True,
        show_constraints=True,
        # parameters of HelpFormatter:
        formatter_settings=HelpFormatter.settings(
            max_width=100,
            col1_max_width=25,
            col2_min_width=30,
            indent_increment=3,
            col_spacing=3,
            row_sep='',  # empty line between definitions
            theme=HelpTheme.dark(),
        )
    )

    @group(context_settings=CONTEXT_SETTINGS)
    # ...
    def main(...):
        ...

    @main.command(
        align_option_groups=True,  # overrides the context setting
        formatter_settings=HelpFormatter.settings(
            col1_max_width=30,  # overrides this specific formatter parameter
        )
    )
    # ...
    def cmd(...):
        ...

## Themes

You can set a “help theme” using the `theme` key of `formatter_settings`. Since your entire application should have a consistent theme, you should set a theme at the context level of your root command:

    SETTINGS = Context.settings(
        formatter_settings=HelpFormatter.settings(
            theme=HelpTheme(...)
        )
    )

    @cloup.group(context_settings=SETTINGS)
    def root_command(...):
        ...

A `HelpTheme` is a collection of styles for several elements of the help page. A “style” is just a function (or a callable) that takes a string and returns a styled version of it. This means you can use your favorite styling/color library (like `rich`, `colorful` etc) with it.

Given that Click has some built-in basic styling functionality provided by the function `click.style()`, Cloup provides the `Style` class, which wraps `click.style` to facilitate its use with `HelpTheme`.

Tip

Cloup also provides an enum-like `Color` class containing all colors supported by Click.

The following picture links `HelpTheme` arguments to the corresponding visual elements of the help page (only `epilog` is missing in the image):

The above image was obtained with the following theme:

    HelpTheme(
        invoked_command=Style(fg='bright_yellow'),
        heading=Style(fg='bright_white', bold=True),
        constraint=Style(fg='magenta'),
        col1=Style(fg='bright_yellow'),
    )

For an always up-to-date list of all possible arguments these classes take, refer to the API reference:

`HelpTheme`([invoked_command, command_help, ...]) | A collection of styles for several elements of the help page.
`Style`([fg, bg, bold, dim, underline, ...]) | Wraps `click.style()` for a better integration with `HelpTheme`.

### Predefined themes

Cloup provides two predefined themes:

`HelpTheme.dark`() | A theme assuming a dark terminal background color.
`HelpTheme.light`() | A theme assuming a light terminal background color.

Ideally, you should select a theme based on the terminal background color or let the user decide which one to use (if any) at the application level.

If you want, you can use the default themes as a base and change only some of the styles using `HelpTheme.with_()`, e.g.:

    theme = HelpTheme.dark().with_(
        col1=Style(fg=Color.bright_green),
        epilog=Style(fg=Color.bright_white, italic=True)
    )

## Row separators

You can specify how to separate the rows/entries of a definition list using the `row_sep` argument of `HelpFormatter`. You may want to use this argument to separate definitions with an empty line in order to improve readability.

Note

`row_sep` only affects the “tabular layout”, not the linear layout.

### A constant separator

To use a separator consistently for all definition lists, you can either pass either:

- a string not ending with `\n`: the formatter will consistently write a newline character after the separator. You can set `row_sep=''` if you want an empty line between rows

- or a function `(width: int) -> str` that generates such a string based on the width of the definition list; this allows you to pass an instance of `Hline` if you want to use horizontal lines. Note that `Hline` is an utility that you can use in other parts of your program as well.

    # No row separator (default)
    row_sep=None

    # Separate rows with an empty line
    row_sep=''

    # Horizontal lines (various styles)
    row_sep=Hline.solid
    row_sep=Hline.dashed
    row_sep=Hline.densely_dashed
    row_sep=Hline.dotted

### Using a separator conditionally

A fixed separator gives a consistent look to your help page but has the drawback of adding the separator even when unneeded (e.g. in the “Commands” section), wasting vertical space.

To overcome this problem, Cloup allows you to specify a “policy” that decides for each individual definition list whether to use a row separator (and which one). Such policy must implement the `RowSepPolicy` interface.

In practice, you will use `RowSepIf`, which takes the following parameters:

- condition – a `RowSepCondition`, i.e. a function that decides, based on the available horizontal space, if a definition list should use a row separator or not

- sep – the separator to use in definition lists that satisfy the `condition`. This may be a string or a `SepGenerator`. The default separator is `sep=""`, which corresponds to an empty line between rows.

Cloup provides the function `multiline_rows_are_at_least()` to create conditions that enable the use of a separator only if the number of rows taking multiple lines is above a certain threshold. The threshold can be specified either as an absolute number or as a percentage relative the total number of rows in the definition list:

    # Insert an empty line only if the definition list has at least 1 multi-line row
    row_sep=RowSepIf(multiline_rows_are_at_least(1))

    # Insert a dotted line only if at least 25% of all rows take multiple lines
    row_sep=RowSepIf(multiline_rows_are_at_least(.25), sep=Hline.dotted)

## The linear layout for definition lists

When the terminal width is “too small” for a standard 2-column definition lists, Cloup `HelpFormatter` switches to a “linear layout”, where

- the option description is always printed below the option name, with an indentation increment of at least 3 spaces

- all definitions are separated by an empty line.

The following tabs compare the `--help` of the manim example (“aligned” and “non-aligned” refer to the `align_option_groups` argument):

Linear layout

    Usage: manim render [OPTIONS]
                        SCRIPT_PATH
                        [SCENE_NAMES]...

      Render some or all scenes defined in a Python
      script.

    Global options:
      -c, --config_file TEXT
         Specify the configuration file to use for
         render settings.

      --custom_folders
         Use the folders defined in the
         [custom_folders] section of the config
         file to define the output folder
         structure.

      --disable_caching
         Disable the use of the cache (still
         generates cache files).

      --flush_cache
         Remove cached partial movie files.

      --tex_template TEXT
         Specify a custom TeX template file.

      -v, --verbosity [DEBUG|INFO|WARNING|ERROR|CRITICAL]
         Verbosity of CLI output. Changes ffmpeg
         log level unless 5+.

    [...]

Standard layout (aligned)

    Usage: manim render [OPTIONS]
                        SCRIPT_PATH
                        [SCENE_NAMES]...

      Render some or all scenes defined in a Python
      script.

    Global options:
      -c, --config_file TEXT      Specify the
                                  configuration
                                  file to use for
                                  render settings.
      --custom_folders            Use the folders
                                  defined in the
                                  [custom_folders]
                                  section of the
                                  config file to
                                  define the output
                                  folder structure.
      --disable_caching           Disable the use
                                  of the cache
                                  (still generates
                                  cache files).
      --flush_cache               Remove cached
                                  partial movie
                                  files.
      --tex_template TEXT         Specify a custom
                                  TeX template
                                  file.
      -v, --verbosity [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                                  Verbosity of CLI
                                  output. Changes
                                  ffmpeg log level
                                  unless 5+.

    [...]

Standard layout (non-aligned)

    Usage: manim render [OPTIONS]
                        SCRIPT_PATH
                        [SCENE_NAMES]...

      Render some or all scenes defined in a Python
      script.

    Global options:
      -c, --config_file TEXT  Specify the
                              configuration file to
                              use for render
                              settings.
      --custom_folders        Use the folders
                              defined in the
                              [custom_folders]
                              section of the config
                              file to define the
                              output folder
                              structure.
      --disable_caching       Disable the use of
                              the cache (still
                              generates cache
                              files).
      --flush_cache           Remove cached partial
                              movie files.
      --tex_template TEXT     Specify a custom TeX
                              template file.
      -v, --verbosity [DEBUG|INFO|WARNING|ERROR|CRITICAL]
                              Verbosity of CLI
                              output. Changes
                              ffmpeg log level
                              unless 5+.
      --notify_outdated_version / --silent
                              Display warnings for
                              outdated
                              installation.

    [...]

The linear layout is used when the available width for the 2nd column is below `col2_min_width`, one of the `formatter_settings`.

You can disable the linear layout settings `col2_min_width=0`.

You make the linear layout your default layout by settings `col2_min_width` to a large number, possibly `math.inf`.

## Minor differences with Click

- The width of the 1st column of a definition list is computed excluding the rows that exceeds `col1_max_width`; this results in a better use of space in many cases, especially with `align_option_groups=False`.

- The default `short_help`’s of commands actually use all the available terminal width (in Click, they don’t; see “Related issue” of this Click issue)

- The command epilog is not indented (this is just my subjective preference).