Improve help text of CLI command descriptions

[jameshadfield]

Currently the formatting of the help messages (defined via the leading docstrings at the start of each script in augur/*.py) is not respected by augur <command> --help. We should improve this which will encourage more detailed help messages. Note that read-the-docs formats things correctly 💯

Example: augur distance

Docstring correctly formatted -- see https://nextstrain-augur.readthedocs.io/en/stable/cli.html#distance

Incorrect formatting:

$ augur distance --help
usage: augur distance [-h] --tree TREE --alignment ALIGNMENT [ALIGNMENT ...]
                      --gene-names GENE_NAMES [GENE_NAMES ...]
                      --attribute-name ATTRIBUTE_NAME [ATTRIBUTE_NAME ...]
                      --compare-to {root,ancestor,pairwise}
                      [{root,ancestor,pairwise} ...] --map MAP [MAP ...]
                      [--date-annotations DATE_ANNOTATIONS]
                      [--earliest-date EARLIEST_DATE]
                      [--latest-date LATEST_DATE] --output OUTPUT

Calculate the distance between sequences across entire genes or at a
predefined subset of sites. Distance calculations require selection of a
comparison method (to determine which sequences to compare) and a distance map
(to determine the weight of a mismatch between any two sequences). Comparison
methods ================== Comparison methods include: #. root: the root and
all nodes in the tree (the previous default for all distances) #. ancestor:
each tip from a current season and its immediate ancestor (optionally, from a
...

Possible solutions

1. CLI: Use raw descriptions #1641
2. Render the rST to plain text (ref)

[tsibley]

This can be done by changing out the help formatter class used by augur's argparse instance.

[tsibley]

I think there's an example of that in the nextstrain/cli code.

[tsibley]

The most basic fix, preserving paragraphs and line wrapping and whitespace, is ensuring that help_formatter=argparse.RawDescriptionHelpFormatter is set on all parsers (see doc) and that help strings are then already correctly formatted (e.g. wrapped if necessary) in the source code.

More extensive improvements would include rendering the rST in these docstrings/descriptions to plain text for use in --help output.

I've done that and a lot of other prior work in Nextstrain CLI's usage of argparse to keep command descriptions readable, including limiting wrapping widths.

[victorlin]

Actually, #1630 is not a duplicate if we scope this issue to descriptions and not all CLI help text. Much more work is needed to improve help text for options, so I think we can treat that as separate. I'll update the issue titles/descriptions to reflect this scoping.