Support for exposing manual pages (#1047)

Co-authored-by: Tzu-ping Chung <[email protected]>
Co-authored-by: chrysle <[email protected]>
Co-authored-by: Jason Lam <[email protected]>

CHANGELOG.md

@@ -25,6 +25,7 @@ automatically upgraded.
 - Fix program name in generated manual page
 - Print all environment variables in `pipx environment`
 - Return an error message when directory can't be added to PATH successfully
+- Expose manual pages included in an application installed with `pipx install`
 
 ## 1.2.1
 

docs/how-pipx-works.md

@@ -8,7 +8,9 @@ When installing a package and its binaries on linux (`pipx install package`) pip
 - create a Virtual Environment in `~/.local/share/pipx/venvs/PACKAGE` that uses the shared pip mentioned above but otherwise is isolated (pipx uses a [.pth file]( https://docs.python.org/3/library/site.html) to do this)
 - install the desired package in the Virtual Environment
 - expose binaries at `~/.local/bin` that point to new binaries in `~/.local/share/pipx/venvs/PACKAGE/bin` (such as `~/.local/bin/black` -> `~/.local/share/pipx/venvs/black/bin/black`)
-- As long as `~/.local/bin/` is on your PATH, you can now invoke the new binaries globally
+- expose manual pages at `~/.local/share/man/man[1-9]` that point to new manual pages in `~/.local/pipx/venvs/PACKAGE/share/man/man[1-9]`
+- as long as `~/.local/bin/` is on your PATH, you can now invoke the new binaries globally
+- on operating systems which have the `man` command, as long as `~/.local/share/man` is a recognized search path of man, you can now view the new manual pages globally
 
 When running a binary (`pipx run BINARY`), pipx will
 
@@ -46,6 +48,16 @@ setup(
 
 In this case `main_func` and `some_func` would be available to pipx after installing the above example package.
 
+To install manual pages, which can be viewed with the `man` command on operating systems which have this command, include a [`data_files` section](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#data-files) in your `setup.py` file.
+```
+setup(
+    # other arguments here...
+    data_files=[('share/man/man1', ['manpage.1'])]
+)
+```
+
+In this case the manual page `manpage.1` would be available to pipx after installing the above example package.
+
 For a real-world example, see [pycowsay](https://github.com/cs01/pycowsay/blob/master/setup.py)'s `setup.py` source code.
 
 You can read more about entry points [here](https://setuptools.pypa.io/en/latest/userguide/quickstart.html#entry-points-and-automatic-script-creation).

docs/installation.md

@@ -67,14 +67,15 @@ Example configuration for use of the code linter [yapf](https://github.com/googl
 ## Installation Options
 
 The default binary location for pipx-installed apps is `~/.local/bin`. This can be overridden with the environment variable `PIPX_BIN_DIR`.
+The default manual page location for pipx-installed apps is `~/.local/share/man`. This can be overridden with the environment variable `PIPX_MAN_DIR`.
 
 pipx's default virtual environment location is typically `~/.local/share/pipx` on Linux/Unix, `%USERPROFILE%\AppData\Local\pipx` on Windows and `~/Library/Application Support/pipx` on macOS, and for compatibility reasons, if `~/.local/pipx` exists, it will be used as the default location instead. This can be overridden with the `PIPX_HOME` environment variable.
 
 As an example, you can install global apps accessible by all users on your system with the following command (on MacOS, Linux, and Windows WSL):
 
 ```
-sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install PACKAGE
-# Example: $ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install cowsay
+sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin PIPX_MAN_DIR=/usr/local/share/man pipx install PACKAGE
+# Example: $ sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin PIPX_MAN_DIR=/usr/local/share/man pipx install cowsay
 ```
 
 !!! note