search

bloomberg / memray

Memray is a memory profiler for Python
https://bloomberg.github.io/memray/
Apache License 2.0
13.17k stars 392 forks source link

docs: Allow producing a `memray.1` man page #524

Closed godlygeek closed 7 months ago

godlygeek commented 8 months ago

This man page will contain a small bit of prose explaining what Memray is and where to find the full documentation, followed by CLI usage information scraped from the --help of each of our subcommands. Distros can build the man page for any given version to include in distro packages of Memray.

godlygeek commented 8 months ago

https://gist.github.com/godlygeek/e3ab347806010596cab9784ccc33f1a8 shows the memray.1 that's generated by running make -C docs man from the repo root (assuming that a virtualenv has been activated and pip install -r requirements-docs.txt has been run to install the docs generation dependencies).

@alexmyczko Can you check if that man page meets your needs? It's more informative than what you propose in #523 and it shouldn't require too much more work to keep up to date.

codecov-commenter commented 8 months ago

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Comparison is base (d491065) 92.37% compared to head (c937da0) 92.32%.

Additional details and impacted files ```diff @@ Coverage Diff @@ ## main #524 +/- ## ========================================== - Coverage 92.37% 92.32% -0.06% ========================================== Files 91 91 Lines 11270 11270 Branches 1571 1571 ========================================== - Hits 10411 10405 -6 - Misses 854 860 +6 Partials 5 5 ``` | [Flag](https://app.codecov.io/gh/bloomberg/memray/pull/524/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=bloomberg) | Coverage Δ | | |---|---|---| | [cpp](https://app.codecov.io/gh/bloomberg/memray/pull/524/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=bloomberg) | `85.66% <ø> (-0.17%)` | :arrow_down: | | [python_and_cython](https://app.codecov.io/gh/bloomberg/memray/pull/524/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=bloomberg) | `95.53% <ø> (ø)` | | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=bloomberg#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

sarahmonod commented 8 months ago

Should we exercise this in CI in some way? At least to ensure that the manual page can be generated and isn't empty for example.

godlygeek commented 8 months ago

Should we exercise this in CI in some way?

Yes, let's.

At least to ensure that the manual page can be generated and isn't empty for example.

I'll make sure it's generated. I'm not gonna check for emptiness - we don't do that for the HTML output, so doing it for the man output seems superflous. But I will update make docs to build the man page, and CI already tests that make docs succeeds.

Let's not worry about the "empty output" case unless we ever find a case where Sphinx generates an empty file and returns a success rcode to us. 😃