スクリプトの文書化—ドキュメントをクリックします

スクリプトの文書化

クリックすると、コマンドラインツールの文書化が非常に簡単になります。 まず、ヘルプページが自動的に生成されます。 現在、これらはレイアウトに関してカスタマイズできませんが、すべてのテキストを変更できます。

ヘルプテキスト

コマンドとオプションはヘルプ引数を受け入れます。 コマンドの場合、関数のdocstringは、提供されている場合は自動的に使用されます。

簡単な例：

そしてそれはどのように見えるか：

議論の文書化

click.argument（）はhelpパラメーターを取りません。 これは、最も必要なものだけに引数を使用するというUnixツールの一般的な規則に従い、名前で参照してコマンドヘルプテキストにそれらを文書化するためです。

説明で引数を参照することをお勧めします。

そしてそれはどのように見えるか：

または、引数の説明を明示的に提供することをお勧めします。

そしてそれはどのように見えるか：

その他の例については、引数の例を参照してください。

再包装の防止

Clickのデフォルトの動作は、端末の幅に基づいてテキストを再折り返すことです。 状況によっては、これが問題になる可能性があります。 主な問題は、改行が重要なコード例を表示するときです。

\bエスケープマーカーのみを含む行を追加することにより、段落ごとに再折り返しを無効にすることができます。 この行はヘルプテキストから削除され、再折り返しは無効になります。

例：

そしてそれはどのように見えるか：

ヘルプテキストの切り捨て

クリックすると、関数docstringからコマンドヘルプテキストが取得されます。 ただし、すでにdocstringを使用して関数の引数を文書化している場合は、ヘルプテキストに：param：行と：return：行を表示したくない場合があります。

\fエスケープマーカーを使用して、マーカーの後のヘルプテキストをクリックして切り捨てることができます。

例：

そしてそれはどのように見えるか：

メタ変数

オプションとパラメーターは、ヘルプページのメタ変数を変更できるmetavar引数を受け入れます。 デフォルトのバージョンは、アンダースコア付きの大文字のパラメーター名ですが、必要に応じて別の注釈を付けることができます。 これは、すべてのレベルでカスタマイズできます。

例：

コマンドショートヘルプ

コマンドの場合、短いヘルプスニペットが生成されます。 デフォルトでは、長すぎない限り、コマンドのヘルプメッセージの最初の文です。 これはオーバーライドすることもできます：

そしてそれはどのように見えるか：

ヘルプパラメータのカスタマイズ

バージョン2.0の新機能。

ヘルプパラメータは、非常に特別な方法でClickに実装されています。 通常のパラメータとは異なり、Click for anyコマンドによって自動的に追加され、自動競合解決を実行します。 デフォルトでは--helpと呼ばれますが、これは変更できます。 コマンド自体が同じ名前のパラメーターを実装している場合、デフォルトのヘルプパラメーターはそのパラメーターの受け入れを停止します。 help_option_names と呼ばれるヘルプパラメータの名前を上書きするために使用できるコンテキスト設定があります。

この例では、デフォルトのパラメータを--helpだけでなく-hと--helpに変更します。

そしてそれはどのように見えるか：