Generating Man Pages From reStructuredText

Posted:	2009-04-24 14:41
Tags:	Python

First install subversion:

$ sudo apt-get install subversion

Then get the rst2man tool from the docutils sandbox:

$ svn co http://svn.berlios.de/svnroot/repos/docutils/trunk/sandbox/manpage-writer/

You'll need to copy the writers/manpage.py file into your docutils/writers directory. I'm using a virtual Python environment so I do so like this:

cd manpage-writer
cp writers/manpage.py ~/env/lib/python2.5/site-packages/docutils-0.5-py2.5.egg/docutils/writers/

Next edit runtests so that the CMD variable points to the virtual Python environment:

CMD="/home/james/env/bin/python tools/rst2man.py --traceback"

Now run the tests:

./runtests

This generates some manpages in the output directory and compares them to the pre-generated ones in the expected directory. There are actually a few differences but it generates the test.man page OK.

Next you will want to test the manpage. Each man page has to appear in the appropriate man section, denoted by a single character:

Section The human readable name
   1    User commands that may be started by everyone.
   2    System calls, that is, functions provided by the kernel.
   3    Subroutines, that is, library functions.
   4    Devices, that is, special files in the /dev directory.
   5    File format descriptions, e.g. /etc/passwd.
   6    Games, self-explanatory.
   7    Miscellaneous, e.g. macro packages, conventions.
   8    System administration tools that only root can execute.
   9    Another (Linux specific) place for kernel routine documentation.
   n    (Deprecated) New documentation, that may be moved to a more appropriate section.
   o    (Deprecated) Old documentation, that may be kept for a grace period.
   l    (Deprecated) Local documentation referring to this particular system.

Since you are likely to be documenting command line tools, your man page will probably be in section 1.

As a test, rename test.man to test.1 then create a .gz file of it and place the compressed file in a directory called man1:

$ cd output
$ mv test.man test.1
$ gzip test.1
$ mkdir man1
$ mv test.1.gz man1

Now you can test the man page like this. The -M ./ options tell man to look in the current directory, not in /usr/share/man.

man -M ./ test

You will now see your output:

rst2man(1)                      text processing                     rst2man(1)

NAME
       rst2man - generate unix manpages from reStructured text

SYNOPSIS
       rst2man --help

       rst2man [ OPTIONS ] [ SOURCE [ destination ] ]

DESCRIPTION
       Run it and examine output.

OPTIONS
       -o x   an option

       -b     another

       For all other options see --help.

EXAMPLES
       rst2man.py xml-schema-catalog.rst xml-schema-catalog.man
              create a manpage from xml-schema-catalog.rst

You can now create your own manpages by following the same procedure.

To generate a man page directly rather than using the runtest you can use this command:

$ cd ../tools
$ ~/env/bin/python tools/rst2man.py path/to/input.txt output.1