all2md.cli.help_formatter

Enhanced help formatter for the all2md CLI.

This module builds a structured catalog of CLI options using the existing DynamicCLIBuilder configuration and renders tiered help output (quick/full/section specific) with importance filtering. Rich output is supported when the rich package is available and requested.

class all2md.cli.help_formatter.HelpRenderer

Bases: object

Render help output from a catalog using quick/full/section filters.

Initialize the help renderer with a catalog.

Parameters:

  • catalog (HelpCatalog) – Structured help content to render.

  • use_rich (bool, default False) – Enable rich formatting when available.

WRAP_WIDTH = 100
CATEGORY_ORDER = ('global', 'parser', 'renderer')
CATEGORY_LABELS = {'global': 'Global options', 'parser': 'Parser options', 'renderer': 'Renderer options'}
__init__(catalog: HelpCatalog, *, use_rich: bool = False) → None

Initialize the help renderer with a catalog.

Parameters:

  • catalog (HelpCatalog) – Structured help content to render.

  • use_rich (bool, default False) – Enable rich formatting when available.

render(selector: str = 'quick') → str

Render help text for the specified selector.

Parameters:

selector (str, default "quick") – Help level: “quick”, “full”, or a specific section/format name.

Returns:

Rendered help text.

Return type:

str

print(selector: str = 'quick', *, stream: Any | None = None) → None

Print formatted help output to the specified stream.

Parameters:

  • selector (str, default "quick") – Help level: “quick”, “full”, or a specific section/format name.

  • stream (file-like, optional) – Output stream. Defaults to stdout.

class all2md.cli.help_formatter.HelpCatalog

Bases: object

Structured representation of CLI options and related metadata.

usage: str
description: str
epilog: str
sections: list[HelpSection]
section_lookup: Dict[str, HelpSection]
format_sections: Dict[str, list[HelpSection]]
subcommands: Sequence[tuple[str, str]]
aliases: Dict[str, str]
get_section(selector: str) → HelpSection | None

Return the section that matches selector (case-insensitive).

get_sections_for_format(selector: str) → list[HelpSection]

Return parser/renderer sections for a format selector.

__init__(usage: str, description: str, epilog: str, sections: list[~all2md.cli.help_formatter.HelpSection], section_lookup: ~typing.Dict[str, ~all2md.cli.help_formatter.HelpSection], format_sections: ~typing.Dict[str, list[~all2md.cli.help_formatter.HelpSection]], subcommands: ~typing.Sequence[tuple[str, str]], aliases: ~typing.Dict[str, str] = <factory>) → None
class all2md.cli.help_formatter.HelpSection

Bases: object

Logical grouping of CLI options for help rendering.

key: str
title: str
description: str
options: list[OptionEntry]
category: str
format_name: str | None
iter_core_options() → Iterable[OptionEntry]

Yield options marked as core importance.

__init__(key: str, title: str, description: str, options: list[OptionEntry], category: str, format_name: str | None) → None
class all2md.cli.help_formatter.OptionEntry

Bases: object

Resolved CLI option metadata for rendering.

option_strings: tuple[str, ...]
dest: str
help_text: str
default: Any
metavar: str | None
choices: Sequence[Any] | None
importance: Literal['core', 'advanced', 'security']
is_flag: bool
is_negated_flag: bool
group_title: str
property is_nested: bool

Return True if the destination represents a nested option.

__init__(option_strings: tuple[str, ...], dest: str, help_text: str, default: Any, metavar: str | None, choices: Sequence[Any] | None, importance: Literal['core', 'advanced', 'security'], is_flag: bool, is_negated_flag: bool, group_title: str) → None
all2md.cli.help_formatter.build_help_renderer(*, use_rich: bool = False) → HelpRenderer

Build a complete help renderer with parser and catalog.

all2md.cli.help_formatter.display_help(selector: str = 'quick', *, use_rich: bool | None = None, stream: Any | None = None) → None

Render help for selector to stdout (or stream) with optional rich output.

When use_rich is None the renderer automatically enables rich output when supported, the target stream is a TTY, and color has not been disabled via NO_COLOR or a dumb terminal.