[MRG] Upgrading command-line docs for sourmash sig subcommands

[keyabarve]

Fixes #1612
Fixes #2070

• Pick a sourmash sig subcommand that doesn't have useful output when run w/o arguments.
• Find the relevant subcommand file.
• In that file, add a description=__doc__ and usage=usage argument to the subparser.add_parser(...) call.
• Initialize the __doc__ and usage strings from the command-line docs.
• This can also be done for many other commands than just the sourmash sig.

[codecov]

Codecov Report

Merging #1714 (4a8431e) into latest (bbbf4f1) will increase coverage by 7.38%.
The diff coverage is 100.00%.

@@            Coverage Diff             @@
##           latest    #1714      +/-   ##
==========================================
+ Coverage   84.43%   91.82%   +7.38%     
==========================================
  Files         130       99      -31     
  Lines       15370    11108    -4262     
  Branches     2192     2192              
==========================================
- Hits        12978    10200    -2778     
+ Misses       2092      608    -1484     
  Partials      300      300              

Flag	Coverage Δ
python	91.82% <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/sig/cat.py	100.00% <100.00%> (ø)
src/sourmash/cli/sig/describe.py	100.00% <100.00%> (ø)
src/sourmash/cli/sig/downsample.py	100.00% <100.00%> (ø)
src/sourmash/cli/sig/export.py	100.00% <100.00%> (ø)
src/sourmash/cli/sig/extract.py	100.00% <100.00%> (ø)
src/sourmash/cli/sig/filter.py	100.00% <100.00%> (ø)
src/sourmash/cli/sig/flatten.py	100.00% <100.00%> (ø)
src/sourmash/cli/sig/intersect.py	100.00% <100.00%> (ø)
src/sourmash/cli/sig/kmers.py	100.00% <100.00%> (ø)
src/sourmash/cli/sig/merge.py	100.00% <100.00%> (ø)
... and 35 more

📣 Codecov can now indicate which changes are the most critical in Pull Requests. Learn more

[ctb]

(I think you should avoid using "Fixes ..." unless it resolves the entire issue; in this case, just use "See #1612" or something similar. Fixes will autoclose the issue when it's merged, which we don't want.)

[keyabarve]

@ctb In src/sourmash/cli/sig/cat.py, when I do this: subparser = subparsers.add_parser('cat', description=__doc__, usage=usage) it says that usage is not defined. Where and how can I define it?
Also, how can I do this: "Initialize the __doc__ and usage strings from the command-line docs."

[ctb]

@ctb In src/sourmash/cli/sig/cat.py, when I do this: subparser = subparsers.add_parser('cat', description=__doc__, usage=usage) it says that usage is not defined. Where and how can I define it?

Please see the documentation for argparse for what usage should be, and also see examples within the current codebase.

Also, how can I do this: "Initialize the __doc__ and usage strings from the command-line docs."

The command-line docs are part of the sourmash documentation and can be found under doc/.

[keyabarve]

@ctb In src/sourmash/cli/sig/cat.py, when I do this: subparser = subparsers.add_parser('cat', description=__doc__, usage=usage) it says that usage is not defined. Where and how can I define it?

Please see the documentation for argparse for what usage should be, and also see examples within the current codebase.

Alright!

Also, how can I do this: "Initialize the __doc__ and usage strings from the command-line docs."

The command-line docs are part of the sourmash documentation and can be found under doc/.

I'm not sure what it means to initialize the strings from the docs.

[ctb]

The command-line docs are part of the sourmash documentation and can be found under doc/.

I'm not sure what it means to initialize the strings from the docs.

There is existing documentation in the doc files. Copy it from there into the codebase.

[keyabarve]

Okay, thanks!

[keyabarve]

@ctb I have added the details for the cat command. Could you please take a look at it and tell me whether I need to make any changes or if I could proceed with other commands?

[ctb]

looks good - does it print out helpful stuff when you do sourmash sig cat -h?

[keyabarve]

looks good - does it print out helpful stuff when you do sourmash sig cat -h?

Thank you. Yes, I think it does. This is the output:

== This is sourmash version 4.1.2.dev6+g87a908c.d20210609. ==
== Please cite Brown and Irber (2016), doi:10.21105/joss.00027. ==

usage: 

### `sourmash signature cat` - concatenate multiple signatures together

Concatenate signature files.

For example,

sourmash signature cat file1.sig file2.sig -o all.sig

will combine all signatures in `file1.sig` and `file2.sig` and put them
in the file `all.sig`.

concatenate signature files

positional arguments:
  signatures

optional arguments:
  -h, --help            show this help message and exit
  --from-file FROM_FILE
                        a text file containing a list of files to load signatures from
  -q, --quiet           suppress non-error output
  -o FILE, --output FILE
                        output signature to this file (default stdout)
  -u, --unique          keep only distinct signatures, removing duplicates (based on md5sum)
  -f, --force           try to load all files as signatures
  -k K, --ksize K       k-mer size; default=31
  --protein             choose a protein signature; by default, a nucleotide signature is used
  --no-protein          do not choose a protein signature
  --dayhoff             build Dayhoff-encoded amino acid signatures
  --no-dayhoff          do not build Dayhoff-encoded amino acid signatures
  --hp, --hydrophobic-polar
                        build hydrophobic-polar-encoded amino acid signatures
  --no-hp, --no-hydrophobic-polar
                        do not build hydrophobic-polar-encoded amino acid signatures
  --dna, --rna, --nucleotide
                        choose a nucleotide signature (default: True)
  --no-dna, --no-rna, --no-nucleotide
                        do not choose a nucleotide signature
  --picklist PICKLIST   select signatures based on a picklist, i.e. 'file.csv:colname:coltype'
  --picklist-require-all
                        require that all picklist values be found or else fail

[keyabarve]

@ctb I was not able to find the command line docs for the ingest and manifest commands. Could you guide me to where I could find them?

[ctb]

@ctb I was not able to find the command line docs for the ingest and manifest commands. Could you guide me to where I could find them?

I think we probably don't have any. Could you make issues to add docs for these commands?

[keyabarve]

@ctb I was not able to find the command line docs for the ingest and manifest commands. Could you guide me to where I could find them?

I think we probably don't have any. Could you make issues to add docs for these commands?

Sure! I'll create 2 different issues.

[keyabarve]

@ctb I have added the required details for all the sig commands. Please review.

[ctb]

On Fri, Aug 13, 2021 at 09:47:40AM -0700, Keya Barve wrote: Sure! Should I create 2 separate issues?

Yep.

[keyabarve]

@ctb Please review.

[keyabarve]

@ctb Should this PR be closed/merged?

[ctb]

@ctb Should this PR be closed/merged?

no, it just needs a lot of input from me, and I don't have time at the moment. No harm in leaving it open for now.

[keyabarve]

Alright, thanks!

[ctb]

notes to self for review:

• run each command with -h to see what it looks like
• verify markdown formatting is properly adjusted, and line lengths are ok