#!/usr/bin/env python
# -*- coding: iso-8859-1 -*-
#
# $Source$
# $Id$
#

"""
Inspect a module and generate module documentation guided by a template.

This program is similar to pydoc, except that it works by using a template to
patch up together bits of the source code in a way that generates readable
documentation that can used as input to the LaTeX documentation tools, to
generate documentation similar to that of Python itself.
"""

__version__ = "$Revision: 1.24 $"
__author__ = "Martin Blais <blais@furius.ca>"

#===============================================================================
# EXTERNAL DECLARATIONS
#===============================================================================

import sys, os, pydoc, inspect, re

#===============================================================================
# LOCAL DECLARATIONS
#===============================================================================

class DocGenParser:
    dirre = re.compile('^__ ([a-z]+)::(.*)$')

    def __init__( self, module, f ):
        self.module = module
        self.f = f

    def parse( self, template ):
        for line in template.splitlines():
            mo = self.dirre.match(line)
            if mo:
                t = getattr(self, 'do_%s' % mo.group(1).strip())
                t(mo.group(2).strip())
            else:
                print >> self.f, line

    def do_module( self, arg ): 
        print >> self.f, inspect.getdoc(self.module)

    def do_func( self, arg ): 
        args = inspect.formatargspec(
            *inspect.getargspec(getattr(self.module, arg)))[1:-1]
        doc = inspect.getdoc(getattr(self.module, arg))
        print >> self.f, '\\begin{funcdesc}{%s}{%s}' % (arg, args)
        print >> self.f, doc
        print >> self.f, '\\end{funcdesc}'
        print >> self.f

#===============================================================================
# MAIN
#===============================================================================

def main():
    import optparse
    parser = optparse.OptionParser(__doc__.strip(), version=__version__)
    opts, args = parser.parse_args()

    if len(args) != 1:
        parser.error('You need to specify a module filename')
    fn = args[0]
    
    module = pydoc.importfile(fn)
    if not hasattr(module, '__docgen__'):
        raise SystemExit('Error: module does not have a __docgen__ template')

    parser = DocGenParser(module, sys.stdout)
    parser.parse(module.__docgen__)
    
if __name__ == '__main__':
    main()