记录脚本 — 单击文档

记录脚本

单击使记录命令行工具变得非常容易。 首先，它会自动为您生成帮助页面。 虽然这些目前在布局方面无法自定义，但所有文本都可以更改。

帮助文本

命令和选项接受帮助参数。 在命令的情况下，如果提供，将自动使用函数的文档字符串。

简单的例子：

以及它的样子：

记录参数

click.argument() 不带 help 参数。 这是为了遵循 Unix 工具的一般约定，即仅将参数用于最必要的事情，并通过按名称引用它们在命令帮助文本中记录它们。

您可能更愿意在描述中引用参数：

以及它的样子：

或者您可能更愿意明确提供参数的描述：

以及它的样子：

有关更多示例，请参阅 Arguments 中的示例。

防止重新包装

Click 的默认行为是根据终端的宽度重新包装文本。 在某些情况下，这可能会成为一个问题。 主要问题是在显示代码示例时，换行符很重要。

通过添加一行仅包含 \b 转义标记的行，可以逐段禁用重新换行。 此行将从帮助文本中删除，并且将禁用重新包装。

例子：

以及它的样子：

截断帮助文本

单击从函数文档字符串中获取命令帮助文本。 但是，如果您已经使用文档字符串来记录函数参数，您可能不希望在帮助文本中看到 :param: 和 :return: 行。

您可以使用 \f 转义标记让 Click 截断标记后的帮助文本。

例子：

以及它的样子：

元变量

选项和参数接受 metavar 参数，该参数可以更改帮助页面中的元变量。 默认版本是带下划线的大写参数名称，但如果需要，可以进行不同的注释。 这可以在所有级别进行定制：

例子：

命令简短帮助

对于命令，会生成一个简短的帮助片段。 默认情况下，它是命令帮助消息的第一句话，除非它太长。 这也可以被覆盖：

以及它的样子：

帮助参数定制

2.0 版中的新功能。

help 参数以一种非常特殊的方式在 Click 中实现。 与常规参数不同，它是由 Click 为任何命令自动添加的，并执行自动冲突解决。 默认情况下它被称为 --help，但这可以改变。 如果命令本身实现了具有相同名称的参数，则默认帮助参数将停止接受它。 有一个上下文设置可用于覆盖名为 help_option_names 的帮助参数的名称。

本示例将默认参数更改为 -h 和 --help，而不仅仅是 --help：

以及它的样子：