Skip to content

topmark.cli.help

topmark / cli / help

Shared helpers for Rich Click command help output.

This module builds small Rich renderables used by rich-click help output.

The helpers are intentionally limited to human-facing command help. They should not be used for machine-readable output, runtime reports, or pipeline rendering. Click remains the authoritative runtime, validation, context, and shell completion layer.

HelpExample dataclass 

HelpExample(*, summary, command_line)

Command-help example shown in a Rich Click epilog.

Attributes:

Name Type Description
summary str

Short human-readable explanation of the command.
command_line str

CLI command line to show below the description.

render_examples_epilog 

render_examples_epilog(examples, *, notes=None)

Build a styled Rich Click epilog for examples and optional notes.

Parameters:

Name Type Description Default
examples Sequence[HelpExample]

Command examples to render in order.

 required
notes Sequence[str] | None

Optional note lines rendered after the examples section.

 None

Returns:

Type Description
Text

A Rich Text renderable suitable for use as a rich-click command
Text

epilog.
Source code in src/topmark/cli/help.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def render_examples_epilog(
    examples: Sequence[HelpExample],
    *,
    notes: Sequence[str] | None = None,
) -> Text:
    """Build a styled Rich Click epilog for examples and optional notes.

    Args:
        examples: Command examples to render in order.
        notes: Optional note lines rendered after the examples section.

    Returns:
        A Rich `Text` renderable suitable for use as a `rich-click` command
        epilog.
    """
    epilog = Text()

    if examples:
        epilog.append("Examples:\n", style="bold")
        for example in examples:
            epilog.append("  # ", style="dim")
            epilog.append(example.summary, style="dim")
            epilog.append("\n")
            epilog.append("  ")
            epilog.append(example.command_line, style="cyan")
            epilog.append("\n")

    if notes:
        if examples:
            epilog.append("\n")
        epilog.append("Notes:\n", style="bold")
        for note in notes:
            epilog.append("  • ", style="dim")
            epilog.append(note)
            epilog.append("\n")

    return epilog