Thursday, August 26, 2010

Installing Man Pages with Distutils

People who read my blog probably remember that I started small project lc-tools which is based on libcloud and provides facilities to control clouds. Since the whole project is basically several Python scripts, I though it would make sense to provide a manual page for each.

At first I had to choose format to use for manual pages. I remember dealing with groff several years ago and decided it's too bothersome for me and will require as much effort as writing all the other Python code. :]

Fortunately, I've spotted ronn which allows to use Markdown for formatting manual pages, and it's a great thing as it allows one to think about content, not the formatting.

Using ronn I created all the man pages quite quickly but then faced another problem: distutils doesn't have facilities to install man pages. That is.

I've managed to implement a temporary (will explain why it is temporary later) solution. The idea is to override default install target this way:

So we just execute after default 'install' target did its job. One important thing is to pass "PREFIX" to make sure that man pages will be installed in correct place.

The script is pretty trivial (19 lines length) and you can see it here.

Ok, so what's wrong with this solution? It forces users to have ronn installed to be able to install man pages. While it's OK for people who clone things from git, it's definitely not OK for people downloading the package from PyPI to force them installing ruby, ronn and friends. So the plan is to modify bdist targets to include generated manpages and modify install target to be able to install cached versions if ronn is not installed on the system.

That doesn't seem to be hard to do, though. I think I will implement it and release a new version.

BTW, ronn allows you create HTML man pages easily, so probably it's time to create a site for lc-tools with extensive documentation.

Update: I've asked this question on stackoverflow and haven't got any responses so far.

No comments:

Post a Comment