[MRG] Adding brief descriptions and `-h/--help` text to sourmash `gather`, `search`, and `compare` #1735

keyabarve · 2021-09-02T18:40:36Z

Addresses #1557

What was done:

Taking information from the command-line docs, https://sourmash.readthedocs.io/en/latest/command-line.html,
- create a draft 'usage' string as in https://github.com/dib-lab/sourmash/blob/latest/src/sourmash/cli/compute.py
- create a docstring at the top of the file, as in https://github.com/dib-lab/sourmash/blob/latest/src/sourmash/cli/compute.py
- add the docstring and usage string to the subparser call, as in https://github.com/dib-lab/sourmash/blob/latest/src/sourmash/cli/compute.py
verify that the usage string is output when you run the command with no arguments
verify that the docstring is contained in the output of -h

Commands fixed:

sourmash gather
sourmash search
sourmash compare

NOTE:
The descriptions for all of the sourmash sig subcommands have been addressed in issue #1612 handled by PR #1714.

codecov · 2021-09-02T18:55:48Z

Codecov Report

Merging #1735 (82d93ec) into latest (c093c57) will increase coverage by 7.38%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           latest    #1735      +/-   ##
==========================================
+ Coverage   82.72%   90.10%   +7.38%     
==========================================
  Files         114       87      -27     
  Lines       12200     8401    -3799     
  Branches     1555     1555              
==========================================
- Hits        10092     7570    -2522     
+ Misses       1850      573    -1277     
  Partials      258      258

Flag	Coverage Δ
python	`90.10% <100.00%> (+<0.01%)`	⬆️
rust	`?`

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
src/sourmash/cli/compare.py	`100.00% <100.00%> (ø)`
src/sourmash/cli/gather.py	`100.00% <100.00%> (ø)`
src/sourmash/cli/search.py	`100.00% <100.00%> (ø)`
src/core/src/ffi/utils.rs
src/core/src/ffi/hyperloglog.rs
src/core/src/index/sbt/mod.rs
src/core/src/signature.rs
src/core/src/ffi/signature.rs
src/core/src/index/search.rs
src/core/src/ffi/mod.rs
... and 20 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c093c57...82d93ec. Read the comment docs.

keyabarve · 2021-09-02T19:13:14Z

@ctb I added the docstring and usage for the gather command, but when I run sourmash gather -h, it does not produce the necessary information, instead it gives an error:

Traceback (most recent call last):
  File "/Users/keya/mambaforge/envs/sourmash_dev/bin/sourmash", line 33, in <module>
    sys.exit(load_entry_point('sourmash', 'console_scripts', 'sourmash')())
  File "/Users/keya/sourmash/src/sourmash/__main__.py", line 5, in main
    args = sourmash.cli.get_parser().parse_args(arglist)
  File "/Users/keya/sourmash/src/sourmash/cli/__init__.py", line 79, in parse_args
    args = super(SourmashParser, self).parse_args(args=args, namespace=namespace)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 1818, in parse_args
    args, argv = self.parse_known_args(args, namespace)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 1851, in parse_known_args
    namespace, args = self._parse_known_args(args, namespace)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 2042, in _parse_known_args
    positionals_end_index = consume_positionals(start_index)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 2019, in consume_positionals
    take_action(action, args)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 1928, in take_action
    action(self, namespace, argument_values, option_string)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 1207, in __call__
    subnamespace, arg_strings = parser.parse_known_args(arg_strings, None)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 1851, in parse_known_args
    namespace, args = self._parse_known_args(args, namespace)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 2060, in _parse_known_args
    start_index = consume_optional(start_index)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 2000, in consume_optional
    take_action(action, args, option_string)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 1928, in take_action
    action(self, namespace, argument_values, option_string)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 1092, in __call__
    parser.print_help()
  File "/Users/keya/sourmash/src/sourmash/cli/__init__.py", line 72, in print_help
    super(SourmashParser, self).print_help()
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 2548, in print_help
    self._print_message(self.format_help(), file)
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 2532, in format_help
    return formatter.format_help()
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 283, in format_help
    help = self._root_section.format_help()
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 214, in format_help
    item_help = join([func(*args) for func, args in self.items])
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 214, in <listcomp>
    item_help = join([func(*args) for func, args in self.items])
  File "/Users/keya/mambaforge/envs/sourmash_dev/lib/python3.9/argparse.py", line 300, in _format_usage
    usage = usage % dict(prog=self._prog)
ValueError: unsupported format character '`' (0x60) at index 1012

I think the error is being thrown at this line:
1.4 Mbp 11.0% 58.0% JANA01000001.1 Fusobacterium sp. OBRC...
at the % 58.0% part, but I'm not sure how to fix this.

Could you provide any hints/suggestions?

keyabarve · 2021-09-04T01:19:26Z

@ctb I noticed that the problem was with the % sign, so I replaced all the % signs with the word "percent" since I couldn't find any other way to fix it. I'm not sure if that's the correct way though.

keyabarve · 2021-09-04T19:01:40Z

I also noticed that the sketch dna, protein, translate commands already have the doc and usage strings.

keyabarve · 2021-09-04T19:39:49Z

@ctb Could you please take a look at what I've written and let me know if I should change anything?

ctb · 2021-09-06T07:50:43Z

On Fri, Sep 03, 2021 at 06:19:36PM -0700, Keya Barve wrote: @ctb I noticed that the problem was with the % sign, so I replaced all the % signs with the word "percent" since I couldn't find any other way to fix it. I'm not sure if that's the correct way though.

try %% - and check out python string formatting :)

keyabarve · 2021-09-09T21:32:22Z

@ctb A few comments:

I was able to fix the errors with the % signs.
I believe the descriptions for all the sourmash sig subcommands is being handled in [MRG] Upgrading command-line docs for sourmash sig subcommands #1714.
I have added the descriptions for the gather, search andcompare commands.
I noticed that for sketch dna, translate and protein, the descriptions already exist in the respective files.

Please let me know if I need to add/change anything else.

keyabarve · 2021-09-17T16:50:02Z

@ctb Please review.

keyabarve · 2021-10-01T00:15:22Z

@mr-eyes Please review.

ctb · 2021-10-01T00:18:06Z

@mr-eyes Please review.

I think this one needs a lot of familiarity with sourmash use cases, so please wait to merge it until I review as well. But it could certainly use interim reviews from @mr-eyes and/or @hehouts :)

hehouts

Looks great to me!

ctb · 2021-10-03T16:02:48Z

hi folks,

I was caught a little bit by surprise when I saw that the Markdown syntax (including links) was simply included in the help text, e.g.

[Jaccard index][3] or
(if signatures are created with `-p abund`) the [angular
similarity](https://en.wikipedia.org/wiki/Cosine_similarity#Angular_distance_and_similarity).

here it's worth noting a few things -

[3] doesn't mean anything at all in this context - it's a numerical link reference to a link in the original doc file, doc/command-line.md.
Markdown syntax isn't rendered at the command line, so in the help text output on the command line we should make sure it makes sense.

I'm working on making the necessary updates, but this is a plea to think about how the user is going to experience the changes and incorporate that into changes and/or reviews. thanks :)

ctb · 2021-10-03T16:05:29Z

It's also worth noting that while markdown->html rendering doesn't pay attention to line breaks, that is NOT true for the text output to command line. So reformatting things so that lines present properly is also worth doing.

ctb · 2021-10-03T16:14:03Z

Hi @keyabarve if you merge in #1747, and everything looks good, we can merge this. Thank you!

ctb · 2021-10-03T16:20:08Z

hi @keyabarve also -

please adjust the PR description at the top of this PR to be accurate and straightforward; this includes eliminating checkboxes that you don't plan on checking, changing the TODO to something like 'What we did', and referencing the right PR for sourmash sig commands, i.e. adding the issue and/or PR to '(Addressed in another issue)'.
reference this PR in a comment over on add brief descriptions and -h/--help text to sourmash commands #1557 stating that gather, search, and compare were handled in this PR, and that the sourmash sig commands are being handled elsewhere.

Basically any sourmash dev should be able to read the top of this PR to figure out what was done (not what you intended to do, or how it was done ;); and any sourmash dev should be able to look at #1557 and see what is left to be done and where it is being done. Thanks!

…e`. (#1747) * reformat compare -h output * reformat/edit gather output * reformat gather, search

ctb

thank you! please merge if & when tests pass!

keyabarve · 2021-10-03T18:15:10Z

Will do! Thanks!

ctb · 2021-10-03T18:27:12Z

🎉

keyabarve added 2 commits September 2, 2021 11:34

Initial commit

394db83

Added gather command details

64dcbc7

Added search command details - fixed errors

4cdc7dd

Added compare command details

9b9e1e4

keyabarve added 2 commits September 7, 2021 12:03

Fixed all errors

591136d

Merge branch 'latest' into KB_1557

0ef0468

keyabarve changed the title ~~[WIP] Adding brief descriptions and -h/--help text to sourmash commands~~ [MRG] Adding brief descriptions and -h/--help text to sourmash commands Sep 10, 2021

hehouts reviewed Oct 2, 2021

View reviewed changes

ctb changed the title ~~[MRG] Adding brief descriptions and -h/--help text to sourmash commands~~ [MRG] Adding brief descriptions and -h/--help text to sourmash gather, search, and compare Oct 3, 2021

ctb mentioned this pull request Oct 3, 2021

[MRG] update help text from #1735 for gather, search, and compare. #1747

Merged

[MRG] update help text from #1735 for gather, search, and `compar…

82d93ec

…e`. (#1747) * reformat compare -h output * reformat/edit gather output * reformat gather, search

keyabarve mentioned this pull request Oct 3, 2021

add brief descriptions and -h/--help text to sourmash commands #1557

Closed

5 tasks

ctb approved these changes Oct 3, 2021

View reviewed changes

keyabarve merged commit d91911b into latest Oct 3, 2021

keyabarve deleted the KB_1557 branch October 3, 2021 18:19

ctb mentioned this pull request Oct 27, 2021

Draft release notes for next release (4.2.3?) #1761

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[MRG] Adding brief descriptions and `-h/--help` text to sourmash `gather`, `search`, and `compare` #1735

[MRG] Adding brief descriptions and `-h/--help` text to sourmash `gather`, `search`, and `compare` #1735

keyabarve commented Sep 2, 2021 •

edited

Loading

codecov bot commented Sep 2, 2021 •

edited

Loading

keyabarve commented Sep 2, 2021

keyabarve commented Sep 4, 2021

keyabarve commented Sep 4, 2021

keyabarve commented Sep 4, 2021

ctb commented Sep 6, 2021 via email

keyabarve commented Sep 9, 2021 •

edited

Loading

keyabarve commented Sep 17, 2021

keyabarve commented Oct 1, 2021

ctb commented Oct 1, 2021

hehouts left a comment

ctb commented Oct 3, 2021

ctb commented Oct 3, 2021

ctb commented Oct 3, 2021

ctb commented Oct 3, 2021

ctb left a comment

keyabarve commented Oct 3, 2021

ctb commented Oct 3, 2021

[MRG] Adding brief descriptions and -h/--help text to sourmash gather, search, and compare #1735

[MRG] Adding brief descriptions and -h/--help text to sourmash gather, search, and compare #1735

Conversation

keyabarve commented Sep 2, 2021 • edited Loading

codecov bot commented Sep 2, 2021 • edited Loading

Codecov Report

keyabarve commented Sep 2, 2021

keyabarve commented Sep 4, 2021

keyabarve commented Sep 4, 2021

keyabarve commented Sep 4, 2021

ctb commented Sep 6, 2021 via email

keyabarve commented Sep 9, 2021 • edited Loading

keyabarve commented Sep 17, 2021

keyabarve commented Oct 1, 2021

ctb commented Oct 1, 2021

hehouts left a comment

Choose a reason for hiding this comment

ctb commented Oct 3, 2021

ctb commented Oct 3, 2021

ctb commented Oct 3, 2021

ctb commented Oct 3, 2021

ctb left a comment

Choose a reason for hiding this comment

keyabarve commented Oct 3, 2021

ctb commented Oct 3, 2021

[MRG] Adding brief descriptions and `-h/--help` text to sourmash `gather`, `search`, and `compare` #1735

[MRG] Adding brief descriptions and `-h/--help` text to sourmash `gather`, `search`, and `compare` #1735

keyabarve commented Sep 2, 2021 •

edited

Loading

codecov bot commented Sep 2, 2021 •

edited

Loading

keyabarve commented Sep 9, 2021 •

edited

Loading