Clarify command line help for report --run_results & --run_matrices

[peterjc]

This PR tries to improve the command line help text for pyani report options --run_results & --run_matrices. Before:

$ pyani report --help
...
  --run_results RUN_RESULTS
                        Report table of results for a pyani run (default:
                        False)
  --run_matrices RUN_MATRICES
                        Report matrices of results for a pyani run (default:
                        False)
...

After:

$ pyani report --help
...
  --run_results RUN_ID  Report table of results for comma separated list of
                        runs (default: False)
  --run_matrices RUN_ID
                        Report matrices of results for comma separated list of
                        runs (default: False)
...

This documents that these arguments can be comma separated lists.

The choice of metavariable name is to match pyani plot:

$ pyani plot --help
...
  --run_id RUN_ID       run ID to plot (default: None)
...

Perhaps the defaults could be consistent - None in both cases?

Type of change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality not to work as expected)
• This change requires a documentation update
• This is a documentation update

Action Checklist

• Work on a single issue/concept (if there are multiple separate issues to address, please use a separate pull request for each)
• Fork the pyani repository under your own account (please allow write access for repository maintainers)
• Set up an appropriate development environment (please see CONTRIBUTING.md)
• Create a new branch with a short, descriptive name
• Work on this branch
  • style guidelines have been followed
  • new code is commented, especially in hard-to-understand areas
  • corresponding changes to documentation have been made
  • tests for the change have been added that demonstrate the fix or feature works
• Test locally with pytest -v non-passing code will not be merged
• Rebase against origin/master
• Check changes with flake8 and black before submission
• Commit branch
• Submit pull request, describing the content and intent of the pull request
• Request a code review
• Continue the discussion at Pull requests section in the pyani repository

[codecov]

Codecov Report

Merging #356 (1da8b66) into master (6a3e18b) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #356   +/-   ##
=======================================
  Coverage   76.24%   76.24%           
=======================================
  Files          52       52           
  Lines        3385     3385           
=======================================
  Hits         2581     2581           
  Misses        804      804           

[baileythegreen]

This is good, and potentially means #332 can be closed, too.

I would suggest changing the metavar to RUN_IDS, which still ties in with pyani plot, but sounds more like it can accept multiple values.

[baileythegreen]

I think a plural metavar might be clearer.

[peterjc]

I did consider RUN_IDS but that extra character meant an extra line for the command line help. But as you wish?

[peterjc]

I think changing the default for these two arguments from False to None would help for #332 - shall I do that too?

[baileythegreen]

I think changing the default for these two arguments from False to None would help for #332 - shall I do that too?

Yes, I think that will clear up a lot of the confusion this causes (me, anyway).

[baileythegreen]

This looks good! I'm closing this, and #332. The documentation for pyani report will need to be updated, but since that is still in a pending PR of mine, I will handle that.

[peterjc]

PS Typo, not issue 3-2-2 but 3-3-2