search

hauntsaninja / pyp

Easily run Python at the shell! Magical, but never mysterious.
MIT License
1.41k stars 39 forks source link

Create a man page for pyp #20

Open naclander opened 4 years ago

naclander commented 4 years ago

Often when I'm writing on off shell scripts that are piped together, I forget various flags and have to refer to man $PROGRAM. Since I'm now using pyp quite often in my shell scripts, it would be fantastic if I could run man pyp and see its documentation as well.

hauntsaninja commented 4 years ago

Thanks for the suggestion!

Unfortunately, it seems a little tricky to install man pages as part of a pip install, especially given that not all platforms use man pages and global installs would interact badly with e.g. virtualenvs.

pyp supports pyp --help for reference. You can use help2man to automatically generate a man page based on this; running something like the following should work:

help2man pyp > /usr/local/share/man/man1/pyp.1

Note, you'll need to have the most recent version of pyp for help2man to work, since up until v0.3.2 I'd forgotten to add --version to pyp.

naclander commented 4 years ago

Unfortunately, it seems a little tricky to install man pages as part of a pip install, especially given that not all platforms use man pages and global installs would interact badly with e.g. virtualenvs.

I'm not sure which platforms don't support man pages. I think it would be nice to have it as part of the package, and then packagers ( for Arch, Debian, etc ), can incorporate those man pages when creating their .deb, .rpm, etc. It doesn't necessarily need to be there for pip, although that would be great as well.

help2man pyp > /usr/local/share/man/man1/pyp.1

That might be good enough for packagers actually.

hauntsaninja commented 4 years ago

I'll get to this at some point. I'm going to hold off for a little bit, since a) few users will benefit as we can't install man pages with pip, b) pyp --help and help2man exist for now, c) keeping the man page in sync with the code and version is a bit of a chore, d) most Python CLI tools don't have man pages (for the same reasons), so many users might not expect one. And of course, if I get more requests, I'll prioritise it :-)

nickodell commented 4 years ago

keeping the man page in sync with the code and version is a bit of a chore

Perhaps we should look at argparse-manpage, which can generate a manpage by looking at your ArgumentParser object. The output looks reasonable:

Screen Shot 2020-06-28 at 1 39 11 PM

Though, it seems like it re-flowed the text which is intended to be a bulleted list, which is not great.

few users will benefit as we can't install man pages with pip

I think this is possible, though hard to do portably. Look at the nose project for inspiration. If you run sudo pip install nose, it will install a manpage, which you can see by running man nosetests. I believe they did this by adding a data_files argument to their setup script, which you can see here.

If you install pyp in a virtualenv, it will put the manpage inside the virtualenv, so man won't be able to find it unless the user updates their $MANPATH. It doesn't cause permissions issues, but it doesn't work either.

I tried this on a Linux system, and it works, but it doesn't seem to work on my Mac.

I could look into this further, if you'd like.