# Updated version of help2md [1] to better match the output of the
# help messages produced when using the Python `argparse` module.
#
# [1] https://github.com/valeriangalliat/help2md

# Uppercase first character in paragraphs
/^[a-z]/ {
    $0 = toupper( substr( $0, 1, 1 ) ) substr( $0, 2 )
}


# Initialize usage section (and optional first usage line).
/^Usage:/ {
    usage = 1
    sub(/^Usage: +/, "\n```bash\n", $0)
    sub(/^Usage:$/, "\n```bash", $0)
    utxt = "\n**Usage:**\n" $0
    next
}

# Format usage code.
usage && /^ +.*$/ {
    sub(/^ +/, " ", $0)
    utxt = utxt $0
    next
}

# Close usage code if after usage
usage && /^$/ {
    usage = 0
    descr = 1
    utxt = utxt "\n```"
    next
}

# Close options
options && /^$/ {
    options = 0
}

# Description? (if so, first text after usage)
descr && /^[a-zA-Z_0-9][a-zA-Z_0-9 ]+.*[^:]$/ {
    descr = 0
    prev = "*" $0 "*"
    $0 = utxt
}

# Initialize options/positional-arguments section
!usage && /^[OP][a-zA-Z_0-9 ]+:$/ {
    if (descr) {
	descr = 0
    }
    options = 1
    $0 = "**" $0 "**\n\nName | Description\n---- | -----------"
}

# Remove .py from command
/[a-z]+[.]py/ {
    sub(/[.]py/, "", $0)
}

# Substitute quote with backquote
/'[^']+'/ {
    sub(/'/, "`", $0)
    sub(/'/, "`", $0)
}

# Join continuation lines with previous line.
/^          / {
    if (options && (prev !~ /` \| /)) {
	sub(/^ */, "` | ", $0)
    } else {
	sub(/^ */, " ", $0)
    }
    prev = prev $0
    next
}

# Format arguments/options table.
!usage && /^  / {
    sub(/^  +/, "`", $0)
    sub(/  +/, "` | ", $0)
}

# Initialize buffered line.
NR == 1 {
    prev = $0
}

# Print line (one line buffered).
NR > 1 {
    print prev
    prev = $0
}

END {
    print prev
}