search

blue-yonder / bonfire

A CLI Graylog Client with Follow Mode
BSD 3-Clause "New" or "Revised" License
72 stars 26 forks source link

add a man page #45

Open lefuturiste opened 1 year ago

lefuturiste commented 1 year ago

Add a man page to get help on how to use this tool.

note: I would be interested by contributing to this repository on this very specific issue

valentin-krasontovitsch commented 1 year ago

hi @lefuturiste and thanks for your interest in this project!

man page sounds cool. could you explain a bit more the motivation for a man page? more concretly, would functions should the man page serve, what content should it contain? Simplest thing I guess would be to replicate the text you get when running --help, but I suppose you/we would want something more?

Also, i have no idea about creating a man page (for a pip package) - would have to read up on that, or lean on you for help.

finally, assuming you would be willing to contribute this, what would you need me to do to help / facilitate?

lefuturiste commented 1 year ago

Yes so the motivation is to follow a kind of standard in a unix environment, man pages offer a way to get a structured documentation of the options and commands of a program. Some people have tools in their shell that can read and have auto completions generated from the man pages (eg. fish IRC).

Although I've seen some pip-shipped CLI projects implement this, it's not really common. Youtube DL devscripts/prepare_manpage.py and HTTPie scripts/generate_man_pages.py are doing that.

For the implementation to get started I would just replicate what's already present in the click declaration. It would be great if this feature would be a part of the click lib.

The goal is to generate a text-file with the right format and then copy the file to /usr/share/man/man1 in the setup.py I heard some people use data_files for that.

I will do some further research on this.

valentin-krasontovitsch commented 1 year ago

sounds great, thank you! I'm gonna try to do some research and read up on it as well.