Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve help text of CLI command descriptions #313

Open
Tracked by #1642
jameshadfield opened this issue Jul 16, 2019 · 4 comments
Open
Tracked by #1642

Improve help text of CLI command descriptions #313

jameshadfield opened this issue Jul 16, 2019 · 4 comments
Labels
bug Something isn't working

Comments

@jameshadfield
Copy link
Member

jameshadfield commented Jul 16, 2019

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
image

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
Copy link
Member

tsibley commented Aug 5, 2019

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

@tsibley
Copy link
Member

tsibley commented Aug 5, 2019

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

@huddlej huddlej added the bug Something isn't working label Jul 4, 2020
@tsibley
Copy link
Member

tsibley commented Aug 13, 2024

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
Copy link
Member

victorlin commented Sep 24, 2024

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.

@victorlin victorlin changed the title improve format of help messages Improve help text of CLI command descriptions Sep 24, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

No branches or pull requests

4 participants