jotaen4tinypilot
commented
5 months ago Adding to this, I think we could also consider updating our documentation regarding the following points:
- How the help text output should be structured
- We have an example in the style guide, but we could make it it’s own section instead of having it implicit in the “Parsing Command Line Flags” section. We could also briefly explain the structure, instead of just demonstrating it. There are also some details missing, like how to declare optional flags.
- We could give some guidance on when to use positional arguments vs. named flags, since this is sometimes tricky to decide.
- We could document in which situations we print the full help text.
- Lately, we’ve been starting to always print the full help text for every input error, e.g. for absent mandatory flags, or for malformed flags. Especially if the help text is long, I found that a little hard to work with, though, because the actual specific error message can get buried, and might be easy to miss. Example: this is the full error output of the
publish-releasescript, if you forget to specify the$GITHUB_TOKENenv variable; only the first of all 52 lines is actually relevant/specific to the error.
- Lately, we’ve been starting to always print the full help text for every input error, e.g. for absent mandatory flags, or for malformed flags. Especially if the help text is long, I found that a little hard to work with, though, because the actual specific error message can get buried, and might be easy to miss. Example: this is the full error output of the
- (Stylistic nit) We could consider switching from
while [[ "$#" -gt 0 ]]; dotowhile (( "$#" > 0 )); dofor parsing flags.
mtlynch
In https://github.com/tiny-pilot/tinypilot/pull/1768, we added a way to parse some flags in our bash script and then pass the remaining flags to a subprocess we call at the end of the script.
We should document this as the standard way of performing this so that we don't have to reinvent the wheel in the future.