summaryrefslogtreecommitdiff
path: root/.github/workflows/ci.yaml
diff options
context:
space:
mode:
authorAdam J. Stewart <ajstewart426@gmail.com>2023-07-13 02:18:23 -0500
committerGitHub <noreply@github.com>2023-07-13 00:18:23 -0700
commitbb7f437bf525091848387db9f152e7e22fe4829e (patch)
treea8305b52301d58dc60ef0e43c4ddeba151236125 /.github/workflows/ci.yaml
parent6312ae846450be37632b054a5ef8e87c2833eb73 (diff)
downloadspack-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/workflows/ci.yaml')
0 files changed, 0 insertions, 0 deletions