diff --git a/Makefile b/Makefile index d53a307300..96d141e917 100644 --- a/Makefile +++ b/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 diff --git a/docs/Makefile b/docs/Makefile index 807ff20d15..f52fc228f9 100644 --- a/docs/Makefile +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index aa14ee19a4..5b4cee9cf2 100644 --- a/docs/conf.py +++ b/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." diff --git a/docs/manpage.rst b/docs/manpage.rst new file mode 100644 index 0000000000..dd0caa84ec --- /dev/null +++ b/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 ``_ 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: