From: Stefano Rivera <stefanor@debian.org>
Date: Wed, 29 Sep 2021 20:27:45 -0700
Subject: Add a script to generate a manpage with argparse-manpage.

Bug-Debian: https://bugs.debian.org/960996
Forwarded: https://github.com/pypa/pipx/pull/744
---
 makefile                |  5 ++++-
 noxfile.py              | 15 +++++++++++++--
 scripts/generate_man.py | 42 ++++++++++++++++++++++++++++++++++++++++++
 src/pipx/main.py        |  5 ++++-
 4 files changed, 63 insertions(+), 4 deletions(-)
 create mode 100644 scripts/generate_man.py

diff --git a/makefile b/makefile
index d86a44b..3f55095 100644
--- a/makefile
+++ b/makefile
@@ -1,4 +1,4 @@
-.PHONY: test docs develop build publish publish_docs lint
+.PHONY: test docs develop build publish publish_docs lint man
 
 develop:
 	pipx run nox -s develop
@@ -20,3 +20,6 @@ watch_docs:
 
 publish_docs:
 	pipx run nox -s publish_docs -r
+
+man:
+	pipx run nox -s build_man -r
diff --git a/noxfile.py b/noxfile.py
index e93ba74..601063f 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -7,6 +7,7 @@ import nox  # type: ignore
 PYTHON_ALL_VERSIONS = ["3.6", "3.7", "3.8", "3.9"]
 PYTHON_DEFAULT_VERSION = "3.9"
 DOC_DEPENDENCIES = [".", "jinja2", "mkdocs", "mkdocs-material"]
+MAN_DEPENDENCIES = [".", "argparse-manpage"]
 LINT_DEPENDENCIES = [
     "black==21.5b1",
     "flake8==3.9.2",
@@ -38,9 +39,9 @@ else:
 # Set nox options
 if PLATFORM == "win":
     # build_docs fail on Windows, even if `chcp.com 65001` is used
-    nox.options.sessions = ["tests", "lint"]
+    nox.options.sessions = ["tests", "lint", "build_man"]
 else:
-    nox.options.sessions = ["tests", "lint", "build_docs"]
+    nox.options.sessions = ["tests", "lint", "build_docs", "build_man"]
 nox.options.reuse_existing_virtualenvs = True
 
 
@@ -225,6 +226,16 @@ def watch_docs(session):
     session.run("mkdocs", "serve")
 
 
+@nox.session(python=PYTHON_DEFAULT_VERSION)
+def build_man(session):
+    session.run("python", "-m", "pip", "install", "--upgrade", "pip")
+    session.install(*MAN_DEPENDENCIES)
+    session.env[
+        "PIPX__DOC_DEFAULT_PYTHON"
+    ] = "typically the python used to execute pipx"
+    session.run("python", "scripts/generate_man.py")
+
+
 @nox.session(python=PYTHON_DEFAULT_VERSION)
 def pre_release(session):
     on_master_no_changes(session)
diff --git a/scripts/generate_man.py b/scripts/generate_man.py
new file mode 100644
index 0000000..ac3230f
--- /dev/null
+++ b/scripts/generate_man.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+import os.path
+import textwrap
+
+from build_manpages.manpage import Manpage
+
+from pipx.main import get_command_parser
+
+
+def main():
+    parser = get_command_parser()
+    parser.man_short_description = parser.description.splitlines()[1]
+
+    manpage = Manpage(parser)
+    body = str(manpage)
+
+    # Avoid hardcoding build paths in manpages (and improve readability)
+    body = body.replace(os.path.expanduser("~"), "~")
+
+    # Add a credit section
+    body += textwrap.dedent(
+        """
+        .SH AUTHORS
+        .IR pipx (1)
+        was written by Chad Smith and contributors.
+        The project can be found online at
+        .UR https://pypa.github.io/pipx/
+        .UE
+        .SH SEE ALSO
+        .IR pip (1),
+        .IR virtualenv (1)
+        """
+    )
+
+    with open("pipx.1", "w") as f:
+        f.write(body)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/src/pipx/main.py b/src/pipx/main.py
index 359cd60..4d6681d 100644
--- a/src/pipx/main.py
+++ b/src/pipx/main.py
@@ -602,8 +602,11 @@ def get_command_parser() -> argparse.ArgumentParser:
     completer_venvs = InstalledVenvsCompleter(venv_container)
 
     parser = argparse.ArgumentParser(
-        formatter_class=LineWrapRawTextHelpFormatter, description=PIPX_DESCRIPTION
+        prog="pipx",
+        formatter_class=LineWrapRawTextHelpFormatter,
+        description=PIPX_DESCRIPTION,
     )
+    parser.man_short_description = PIPX_DESCRIPTION.splitlines()[1]
 
     subparsers = parser.add_subparsers(
         dest="command", description="Get help for commands with pipx COMMAND --help"
