Function generate_command_help

docs/generate_cli_docs.py:182–223

(
    ctx: click.Context, command: click.Command, parent_name: str | None = None
)

def generate_command_help(
    ctx: click.Context, command: click.Command, parent_name: str | None = None
) -> StrGenerator:
    # TODO: Add references to long options. Requires splitting out examples.
    # TODO: Add references to subcommands. Need to add actual refs, since programs can't be ref'd.
    # TODO: Handle dollar signs in examples by having both escaped and unescaped versions
    yield f"\n.. _command-{command.name}:\n"
    yield "\n.. program:: %s\n\n" % (
        command.name if parent_name is None else f"{parent_name} {command.name}"
    )
    if parent_name:
        yield from generate_title(f"``{command.name}``", 1)

    replacements = [
        opt
        for opts in [param.opts for param in command.params if hasattr(param, "opts")]
        for opt in opts
    ]

    help = command.help
    help = help.replace(
        "Examples:\n", "".join(generate_title("Examples", 0 if not parent_name else 2))
    )
    help = help.replace("\b\n", "")
    help = help.format(scenedetect="scenedetect", scenedetect_with_video="scenedetect -i video.mp4")
    help = transform_backquotes(help)
    help = transform_add_option_refs(help, replacements)

    for line in help.strip().splitlines():
        if line.startswith(INDENT):
            indent = line.count(INDENT)
            line = line.strip()
            yield f"{indent * INDENT}``{line}``\n" if line else "\n"
        else:
            yield f"{line}\n"

    if command.params:
        yield "\n"
        yield from generate_title("Options", 0 if not parent_name else 2)
        for param in command.params:
            yield from format_option(command, param, replacements)
    yield "\n"


def generate_subcommands(ctx: click.Context, commands: list[str]) -> StrGenerator: