Man Page Generation

Feature: generate man page content from a Cmdln subclass

Added in cmdln.py 1.2.0. Issue 7.

You can generate man page content for a Cmdln subclass with the cmdln.man_sections_from_cmdln() function. This function generates a list of man sections -- in case you would like to manually add additional sections to the final man page content.

    man_sections_from_cmdln(inst, summary=None, description=None, author=None)
        Return man page sections appropriate for the given Cmdln instance.
        Join these sections for man page content.
        
        The man page sections generated are:
            NAME
            SYNOPSIS
            DESCRIPTION  (if `description` is given)
            OPTIONS
            COMMANDS
            HELP TOPICS (if any) 
        
        @param inst {Cmdln} Instance of Cmdln subclass for which to generate
            man page content.
        @param summary {str} A one-liner summary of the command.
        @param description {str} A description of the command. If given,
            it will be used for a "DESCRIPTION" section.
        @param author {str} The author name and email for the AUTHOR secion
            of the man page.
        @raises {ValueError} if man page content cannot be generated for the
            given class.

Given a Cmdln subclass like conan.Conan from the GettingStarted docs, you can generate a man page as follows:

>>> import cmdln
>>> import conan
>>> sections = cmdln.man_sections_from_cmdln(conan.Conan())
>>> open("conan.1", "w").write(''.join(sections))

The cmdln sources include a helper mkmanpage.py script to do this from the command line:

PYTHONPATH=docs python bin/mkmanpage.py conan.Conan > conan.1

That "conan.1" looks like this:

.\" Automatically generated by cmdln 1.2.0
.TH CONAN "1" "Jun 2009" "conan" "User Commands"
.SH NAME
conan

.SH SYNOPSIS
.B conan
[\fIGLOBALOPTS\fR] \fISUBCOMMAND \fR[\fIOPTS\fR] [\fIARGS\fR...]
.br
.B conan
\fIhelp SUBCOMMAND\fR
.SH OPTIONS
.TP
.B -h, --help
show this help message and exit
.SH COMMANDS
.PP
.SS crush
crush your enemies!

Usage:
    conan crush [ENEMIES...]

Options:
    -h, --help          show this help message and exit
    -w WEAPON, --weapon=WEAPON
                        what weapon should Conan use?

C.f. Conan the Barbarian.

.PP
.SS hello
Conan greets thee

.PP
.SS help (?)
give detailed help on a specific sub-command

Usage:
    conan help [COMMAND]

.PP
.SS what_is_best_in_life (best, what_is_best)
Big monologue

which results in a man page that looks like this:

CONAN(1)                           User Commands                           CONAN(1)

NAME
       conan

SYNOPSIS
       conan [GLOBALOPTS] SUBCOMMAND [OPTS] [ARGS...]
       conan help SUBCOMMAND

OPTIONS
       -h, --help
              show this help message and exit

COMMANDS
   crush
       crush your enemies!

       Usage:
           conan crush [ENEMIES...]

       Options:
           -h, --help          show this help message and exit
           -w WEAPON, --weapon=WEAPON
                               what weapon should Conan use?

       C.f. Conan the Barbarian.

   hello
       Conan greets thee

   help (?)
       give detailed help on a specific sub-command

       Usage:
           conan help [COMMAND]

   what_is_best_in_life (best, what_is_best)
       Big monologue

conan                                 Jun 2009                             CONAN(1)