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 <http://www.schweikhardt.net/man_page_howto.html#q4>`_, 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

Further reading:

* http://docutils.sourceforge.net/sandbox/manpage-writer/rst2man.txt 
* http://www.schweikhardt.net/man_page_howto.html