Generating python CLI man page
Question:
I am developing a python CLI tool (using optparse in python2.6, but hope to switch soon to python2.7) and I am about to write the man page.
I have some experience on generating dynamic man pages by:
- creating a dedicated method that composes a string in pod format and writes it to a file
- executing the pod2man command to generate data in groff format to be passed to the man command
I would also like to generate wiki pages with the same content as the man page (with pod I can generate html through pod2html, and probably the html can be easily translated into wiki format).
Has someone a better idea/flow on how to do this?
One thing I have found as interesting is on this link: Creating Man Pages Using optparse and distutils
Answers:
The usual way to generate documentation in Python is to use Sphinx. For example, that’s what’s used in the official Python documentation. Once you have a Sphinx documentation project set up (see this tutorial), you can generate man pages from your Sphinx documentation files via make man. You should also alter the configuration in conf.py to produce appropriate output.
(It’s worth noting that while Sphinx is the usual tool for writing documentation in Python, that doesn’t mean it’s the usual tool for generating man pages. Use what you want!)
While sphinx is a really great documentation system, it’s awfully complex and hard to master. If you need a bang solution, I suggest you look in my project build_manpage.py.
It is not a replacement for properly documenting you projects (with sphinx or what ever way you choose). But it has some immediate benefits for a Python programmer:
- You don’t have to learn the
man syntax.
- You don’t have to learn
rst syntax (never the less, you should one day learn it …)
-
You don’t need to maintain your optparserargparser and a man page formated in external file (in man, rst, or any other conversion system).
-
You simply add one file to you build configuration, and a man page is created for you!
If you do want to use a more complicated system, with a lot of bells and whistles, sphinx allows you convert an rst formated page to man page. And a recently young project, takes a similar approach to my parser and scans your ArgumentParser to produce an rst formatted page,with sphinx directives (such that you don’t need to write it yourself.
(In contrast my scanner produces a man page directly).
Note that this is now part of a pull request to add a manpage formatter in the standard library.
If you are using click you can use click-man.
It can generate man pages from click applications.
One thing I have found as interesting is on this link: Creating Man Pages Using optparse and distutils
As a direct follow-up to the post you mentioned:
There’s now a possibility to use the argparse-manpage project.
I am developing a python CLI tool (using optparse in python2.6, but hope to switch soon to python2.7) and I am about to write the man page.
I have some experience on generating dynamic man pages by:
- creating a dedicated method that composes a string in pod format and writes it to a file
- executing the pod2man command to generate data in groff format to be passed to the man command
I would also like to generate wiki pages with the same content as the man page (with pod I can generate html through pod2html, and probably the html can be easily translated into wiki format).
Has someone a better idea/flow on how to do this?
One thing I have found as interesting is on this link: Creating Man Pages Using optparse and distutils
The usual way to generate documentation in Python is to use Sphinx. For example, that’s what’s used in the official Python documentation. Once you have a Sphinx documentation project set up (see this tutorial), you can generate man pages from your Sphinx documentation files via make man. You should also alter the configuration in conf.py to produce appropriate output.
(It’s worth noting that while Sphinx is the usual tool for writing documentation in Python, that doesn’t mean it’s the usual tool for generating man pages. Use what you want!)
While sphinx is a really great documentation system, it’s awfully complex and hard to master. If you need a bang solution, I suggest you look in my project build_manpage.py.
It is not a replacement for properly documenting you projects (with sphinx or what ever way you choose). But it has some immediate benefits for a Python programmer:
- You don’t have to learn the
mansyntax. - You don’t have to learn
rstsyntax (never the less, you should one day learn it …) -
You don’t need to maintain your optparserargparser and a man page formated in external file (in man, rst, or any other conversion system).
-
You simply add one file to you build configuration, and a man page is created for you!
If you do want to use a more complicated system, with a lot of bells and whistles, sphinx allows you convert an rst formated page to man page. And a recently young project, takes a similar approach to my parser and scans your ArgumentParser to produce an rst formatted page,with sphinx directives (such that you don’t need to write it yourself.
(In contrast my scanner produces a man page directly).
Note that this is now part of a pull request to add a manpage formatter in the standard library.
If you are using click you can use click-man.
It can generate man pages from click applications.
One thing I have found as interesting is on this link: Creating Man Pages Using optparse and distutils
As a direct follow-up to the post you mentioned:
There’s now a possibility to use the argparse-manpage project.