diff options
| author | Adam J. Stewart <ajstewart426@gmail.com> | 2023-07-13 02:18:23 -0500 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-07-13 00:18:23 -0700 |
| commit | bb7f437bf525091848387db9f152e7e22fe4829e (patch) | |
| tree | a8305b52301d58dc60ef0e43c4ddeba151236125 /.github | |
| parent | 6312ae846450be37632b054a5ef8e87c2833eb73 (diff) | |
| download | spack-bb7f437bf525091848387db9f152e7e22fe4829e.tar.gz spack-bb7f437bf525091848387db9f152e7e22fe4829e.tar.bz2 spack-bb7f437bf525091848387db9f152e7e22fe4829e.tar.xz spack-bb7f437bf525091848387db9f152e7e22fe4829e.zip | |
Standardize subcommand help strings (#38804)
### Rationale
While working on #29549, I noticed a lot of inconsistencies in our argparse help messages. This is important for fish where these help messages end up as descriptions in the tab completion menu. See https://github.com/spack/spack/pull/29549#issuecomment-1627596477 for some examples of longer or more stylized help messages.
### Implementation
This PR makes the following changes:
- [x] help messages start with a lowercase letter.
- [x] Help messages do not end with a period
- [x] the first line of a help message is short and simple
longer text is separated by an empty line
- [x] "help messages do not use triple quotes"
"""(except docstrings)"""
- [x] Parentheses not needed for string concatenation inside function call
- [x] Remove "..." "..." string concatenation leftover from black reformatting
- [x] Remove Sphinx argument docs from help messages
The first 2 choices aren't very controversial, and are designed to match the syntax of the `--help` flag automatically added by argparse. The 3rd choice is more up for debate, and is designed to match our package/module docstrings. The 4th choice is designed to avoid excessive newline characters and indentation. We may actually want to go even further and disallow docstrings altogether.
### Alternatives
Choice 3 in particular has a lot of alternatives. My goal is solely to ensure that fish tab completion looks reasonable. Alternatives include:
1. Get rid of long help messages, only allow short simple messages
2. Move longer help messages to epilog
3. Separate by 2 newline characters instead of 1
4. Separate by period instead of newline. First sentence goes into tab completion description
The number of commands with long help text is actually rather small, and is mostly relegated to `spack ci` and `spack buildcache`. So 1 isn't actually as ridiculous as it sounds.
Let me know if there are any other standardizations or alternatives you would like to suggest.
Diffstat (limited to '.github')
0 files changed, 0 insertions, 0 deletions