docs: Allow producing a memray.1 man page

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.

Signed-off-by: Matt Wozniski <mwozniski@bloomberg.net>

Makefile

@@ -124,6 +124,7 @@ lint:  ## Lint all files
 docs:  ## Generate documentation
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
+	$(MAKE) -C docs man
 
 .PHONY: docs-live
 docs-live:  ## Serve documentation on localhost:8000, with live-reload

docs/Makefile

@@ -25,6 +25,12 @@ html:
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man -D exclude_patterns= $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The man pages are in $(BUILDDIR)/man."
+
 .PHONY: livehtml
 livehtml:
 	$(SPHINXAUTOBUILD) -a $(ALLSPHINXOPTS) $(BUILDDIR)/html

docs/conf.py

@@ -2,6 +2,8 @@
 
 import os
 
+import memray.commands
+
 # -- General configuration ------------------------------------------------------------
 
 # The name of a reST role (builtin or Sphinx extension) to use as the default role,
@@ -24,6 +26,10 @@
     "sphinxarg.ext",
 ]
 
+# Don't build our manpage document when we're using the HTML builder.
+# We override this setting when we build with the manpage builder.
+exclude_patterns = ["manpage.rst"]
+
 # General information about the project.
 project = "memray"
 author = "Pablo Galindo Salgado"
@@ -44,6 +50,11 @@
 }
 html_favicon = "favicon.ico"
 
+# -- Options for man pages ------------------------------------------------------------
+man_pages = [
+    ("manpage", "memray", "Python memory profiler", "", 1),
+]
+
 # -- Options for smartquotes ----------------------------------------------------------
 
 # Disable the conversion of dashes so that long options like "--find-links" won't
@@ -66,3 +77,12 @@
 # but we don't want different output depending on the terminal width where the
 # docs were built.
 os.environ["COLUMNS"] = "88"
+
+# -- Improving man page generation ----------------------------------------------------
+
+# The :manpage: mode of sphinx-argparse doesn't allow you to fully override the
+# parser's description with a custom reStructuredText one as it should. Work
+# around this by providing the first sentence of our desired description as the
+# parser's description, and then letting the argparse role append the rest of
+# the intended description. This description doesn't go into the HTML docs.
+memray.commands._DESCRIPTION = "Memray is a memory profiler for Python applications."

docs/manpage.rst

@@ -0,0 +1,124 @@
+:orphan:
+
+Overview
+========
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :manpage:
+   :nosubcommands:
+
+   Memray can track memory allocations in Python code, in native extension modules, and in the Python
+   interpreter itself. It can generate several different types of reports to help you analyze the captured
+   memory usage data. While commonly used as a CLI tool, it can also be used as a library to perform more
+   fine-grained profiling tasks.
+
+   Most commonly you will use the ``memray run`` subcommand to create a capture file, and then use a reporter
+   like the ``memray flamegraph`` subcommand to analyze it.
+
+   .. note::
+
+       This manual page only documents usage of the Memray subcommands that can be invoked from the command line.
+       See `<https://bloomberg.github.io/memray/overview.html>`_ for the full Memray documentation, which
+       includes advice for interpreting Memray reports, example programs, API documentation, information about
+       integrating Memray into Jupyter notebooks and pytest test suites, explanations to help you understand how
+       Python uses memory and how Memray gathers information about memory usage, and more.
+
+RUN SUB-COMMAND
+---------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: run
+   :nodefaultconst:
+   :noepilog:
+
+FLAMEGRAPH SUB-COMMAND
+----------------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: flamegraph
+   :nodefaultconst:
+   :noepilog:
+
+TABLE SUB-COMMAND
+-----------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: table
+   :nodefaultconst:
+   :noepilog:
+
+LIVE SUB-COMMAND
+----------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: live
+   :nodefaultconst:
+   :noepilog:
+
+TREE SUB-COMMAND
+----------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: tree
+   :nodefaultconst:
+   :noepilog:
+
+PARSE SUB-COMMAND
+-----------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: parse
+   :nodefaultconst:
+   :noepilog:
+
+SUMMARY SUB-COMMAND
+-------------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: summary
+   :nodefaultconst:
+   :noepilog:
+
+STATS SUB-COMMAND
+-----------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: stats
+   :nodefaultconst:
+   :noepilog:
+
+TRANSFORM SUB-COMMAND
+---------------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: transform
+   :nodefaultconst:
+   :noepilog:
+
+ATTACH SUB-COMMAND
+------------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: attach
+   :nodefaultconst:
+   :noepilog:
+
+DETACH SUB-COMMAND
+------------------
+
+.. argparse::
+   :ref: memray.commands.get_argument_parser
+   :path: detach
+   :nodefaultconst:
+   :noepilog: