Command descriptions mangled in --help output

[tsibley]

Several commands describe themselves in their module docstring, which they provide to the argparse parser as their description. However, the argparse formatter configuration mangles these descriptions into one big paragraph, making them less readable. To pick the first example I saw, consider augur ancestral's docstring

augur/augur/ancestral.py

Lines 1 to 24 in 66e903a

	"""
	Infer ancestral sequences based on a tree.
	The ancestral sequences are inferred using `TreeTime <https://academic.oup.com/ve/article/4/1/vex042/4794731>`_.
	Each internal node gets assigned a nucleotide sequence that maximizes a
	likelihood on the tree given its descendants and its parent node.
	Each node then gets assigned a list of nucleotide mutations for any position
	that has a mismatch between its own sequence and its parent's sequence.
	The node sequences and mutations are output to a node-data JSON file.
	If amino acid options are provided, the ancestral amino acid sequences for each
	requested gene are inferred with the same method as the nucleotide sequences described above.
	The inferred amino acid mutations will be included in the output node-data JSON
	file, with the format equivalent to the output of `augur translate`.
	The nucleotide and amino acid sequences are inferred separately in this command,
	which can potentially result in mismatches between the nucleotide and amino
	acid mutations. If you want amino acid mutations based on the inferred
	nucleotide sequences, please use `augur translate`.
	.. note::
	The mutation positions in the node-data JSON are one-based.
	"""

vs. its --help output:

$ augur ancestral --help
usage: augur ancestral [-h] --tree TREE [--alignment ALIGNMENT]             
                       [--vcf-reference FASTA | --root-sequence FASTA/GenBank]
                       [--inference {joint,marginal}]                                          
                       [--keep-ambiguous | --infer-ambiguous]                                  
                       [--keep-overhangs] [--annotation ANNOTATION]      
                       [--genes GENES [GENES ...]]
                       [--translations TRANSLATIONS]                                           
                       [--output-node-data OUTPUT_NODE_DATA]
                       [--output-sequences OUTPUT_SEQUENCES]          
                       [--output-translations OUTPUT_TRANSLATIONS]
                       [--output-vcf OUTPUT_VCF]
                       [--validation-mode {error,warn,skip}]                                   
                                                                                               
Infer ancestral sequences based on a tree. The ancestral sequences are                         
inferred using `TreeTime                                                                       
<https://academic.oup.com/ve/article/4/1/vex042/4794731>`_. Each internal node
gets assigned a nucleotide sequence that maximizes a likelihood on the tree   
given its descendants and its parent node. Each node then gets assigned a list
of nucleotide mutations for any position that has a mismatch between its own                   
sequence and its parent's sequence. The node sequences and mutations are    
output to a node-data JSON file. If amino acid options are provided, the
ancestral amino acid sequences for each requested gene are inferred with the
same method as the nucleotide sequences described above. The inferred amino
acid mutations will be included in the output node-data JSON file, with the
format equivalent to the output of `augur translate`. The nucleotide and amino
acid sequences are inferred separately in this command, which can potentially
result in mismatches between the nucleotide and amino acid mutations. If you
want amino acid mutations based on the inferred nucleotide sequences, please
use `augur translate`. .. note:: The mutation positions in the node-data JSON
are one-based.

…

[jameshadfield]

Isn't this #313?

[tsibley]

Doh, yes.