cli-help-style

CLI Help Style

Overview

Guidelines for writing consistent, terminal-friendly help text in the deadline CLI's click command docstrings.

Usage

Use this skill when:

• Adding a new CLI command or subcommand
• Editing existing CLI help text or option descriptions
• Reviewing a PR that modifies CLI docstrings

Core Concepts

Dual rendering: terminal and docs site

These docstrings are rendered in two places:

1. Terminal — deadline <command> --help via click's built-in formatter
2. Docs site — https://aws-deadline.github.io/deadline-cloud/ via mkdocs-click, which passes docstring text through MkDocs as markdown

Click's terminal formatter treats docstrings as plain text with paragraph reflowing. It does not understand markdown — backticks, links, and lists all render literally. MkDocs, on the other hand, renders the same text as markdown, so backticks become <code> tags and links become clickable.

This dual rendering drives most of the style rules below. The goal is text that looks good in both contexts, prioritizing the terminal since that's where most users encounter it.

The ContextTrackingCommand and ContextTrackingGroup classes in _main.py override format_help_text to strip markdown at display time using _markdown_strip.py. This means you can write markdown in docstrings and get clean output in both contexts.

Docstring Structure

Every command docstring MUST follow this order:

1. One-line summary (what the command does)
2. Additional context (optional, 1-3 sentences max)
3. Documentation URL (required for groups and most leaf commands)

Example:

def my_command():
    """
    List the available Deadline Cloud farms or get details of a specific farm.

    \b
    Documentation: https://docs.aws.amazon.com/deadline-cloud/latest/userguide/farms.html
    """

Group Commands

Group docstrings MUST hint at the available subcommands so users can discover capabilities without running --help on each one.