Handling manpages

How would this feature be useful? Some packages, like ipython and ranger-fm come with man pages. It would be nice to provide these, such that man ipython will work.

Describe the solution you’d like

Much like we ask users to ensure ~/.local/bin is on their PATH and we manage symlinks there. We could manage symlinks to man pages in a location and ask them to add a MANDATORY_MANPATH or MANPATH_MAP line to their .manpath file.

Describe alternatives you’ve considered

I tried globbing ~/.local/pipx/venvs/*/share/man in my man config. But didn’t succeed. Adding a line for each installed package does work as expected, so that’s why I think automating the process would be ideal.

I’m willing and able to implement this. I just wanted to open discussion first instead of immediately coming with an elaborate PR.

[uranusjr]

Option 1 is probably the easiest path for now since there’s no suitable metadata for specifying file location now (entry point is close but it’s designed for Python files and I’m not sure if people would think it’s a good idea for us to use it like this). If enough projects catch on, we’d have more ground to push for a metadata standard.

So the next steps for anyone interested in implementing this would be:

1. Add documentation that pipx would look for man page files inside ${DATA_DIRECTORY}/data/share/man/.
2. Implement logic for the above; more specifically, the installation process would install those as wheel data files into the environment, and pipx should pick those up and symlink/copy them into (say) ${PIPX_HOME}/share/man, like we do for entry points (inside ${PIPX_HOME}/bin).
3. Tell projects they can put man page files there for pipx to pick up. Listen to feedback and improve things, eventually producing an Informational PEP to make this into a standard.

[ilyagr]

The following script seems to work for me. I called it pipx-manpage-install.

You need to have stow installed. For man to find the manpages, ~/.local/share/man needs to be in the output of the manpath command. It is there on my debian system by default, though I’m not sure how it got there.

The --ignore pattern comes from https://unix.stackexchange.com/a/293676/261949.

#!/bin/bash
# Create links from `~/.local/share` to the files in `share` subdirectories
# of virtual environments installed with `pipx`.

# Run with `-n` option for a dry run, with `-D` to undo.
# You may have to resolve conflicts manually.
# Assumes there are only directories in the venv dir.

cd $(pipx environment -v PIPX_LOCAL_VENVS)
stow --ignore='^((?!share).)*$' --target=$(realpath ~/.local) -v $@ *