Miscellaneous improvements to our documentation and help messages #467
Conversation
Match the spelling used by the Python documentation. Signed-off-by: Matt Wozniski <mwozniski@bloomberg.net>
Prior to this change, our one-sentence description of each Memray command would show up in the `memray --help` output (next to the name of each subcommand), but wouldn't show up in the `memray subcommand --help` output (at the top of the output, above the usage text), nor in the generated CLI documentation in our HTML pages. Including this looks nicer and improves readability for the help text. Signed-off-by: Matt Wozniski <mwozniski@bloomberg.net>
If we don't do this, apparently `sphinx-argparse` inherits the `argparse` default of formatting the help messages as wide as the terminal that the docs are being built in, which results in different widths for the pre-formatted usage text in our HTML documentation depending on who builds the docs and how they do it. Signed-off-by: Matt Wozniski <mwozniski@bloomberg.net>
We tried to be clever and avoid unnecessary work by skipping the building and testing of wheels when only documentation was changed, but this doesn't play nicely with our GitHub branch protection rules, since it means that we never get the successful status checks that we require. We could probably do something more clever to make the status check immediately succeed without doing any real work when only documentation was changed, but for now let's just revert back to doing the extra work. Signed-off-by: Matt Wozniski <mwozniski@bloomberg.net>
This reverts commit 66a88b5. Apparently codecov-action v4 is still a beta release. After we upgraded to it, the maintainers changed its tags to correctly flag it as beta, and now GitHub Actions is refusing to use it. Let's downgrade back to v3 for now. Signed-off-by: Matt Wozniski <mwozniski@bloomberg.net>
Codecov ReportAll modified lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #467 +/- ##
==========================================
- Coverage 91.97% 91.94% -0.03%
==========================================
Files 91 91
Lines 10803 10803
Branches 1485 1485
==========================================
- Hits 9936 9933 -3
- Misses 865 868 +3
Partials 2 2
Flags with carried forward coverage won't be shown. Click here to find out more.
☔ View full report in Codecov by Sentry. |
| # Limit the width of usage messages. argparse defaults to the terminal width, | ||
| # but we don't want different output depending on the terminal width where the | ||
| # docs were built. | ||
| os.environ["COLUMNS"] = "88" |
There was a problem hiding this comment.
Much better, thank you for this change it is indeed much clearer this way 👍🏼
There was a problem hiding this comment.
I think the last push to the docs was done manually by me, in a fullscreen terminal on a widescreen monitor, and I think that's why the usage summaries are currently a one-line mess with a scrollbar. I don't think we would have gotten a scrollbar had we let CI do an automated publish, because I don't think it would have wound up with the idea that the screen is so wide.
But also to be fair, I had no idea my environment was bleeding into the generated docs like this, so yeah, it's definitely much wiser to hardcode a sane value instead.
Before adding a
description=to ourArgumentParser's:After:
Before setting
COLUMNSin ourdocs/conf.py:After:
