root/NXLucene/trunk/doc/build_doc

#!/usr/bin/env python

#
# Taken from :
# http://cvs.sourceforge.net/viewcvs.py/cctools/publisher/build_doc?rev=1.3
#
# A bit refactored.
#
# $Id: $

# system
### Twisted Preamble
# This makes sure that users don't have to set up their environment
# specially in order to run these programs from bin/.
import sys, os, string, shutil
#if string.find(os.path.abspath(sys.argv[0]), os.sep+'Twisted') != -1:
#    sys.path.insert(0, os.path.normpath(os.path.join(os.path.abspath(sys.argv[0]
#), os.pardir, os.pardir)))
#sys.path.insert(0, os.curdir)
### end of preamble

import os, sys
tmp_dir = '_epyrun_tmp' #only used for partial builds

# HACK: Don't import stuff that we don't like
# this is why we have to convert 
def myimport(*args):
    try: 
        return im(*args)
    except:
        mod = FakeModule(args[0], 4)
        i = args[0].rfind('.')
        if i != -1:
            setattr(sys.modules[args[0][:i]], args[0][i+1:], mod)
        return mod

class FakeModule:

    def __init__(self, name, level):
        self.__level = level
        self.__name__ = name

    def __repr__(self):
        return '<Fake %s>' % self.__name__
    __str__ = __repr__

    def __nonzero__(self):
        return 1

    def __call__(self, *args, **kw):
        pass #print 'Called:', args

    def __getattr__(self, attr):
        if self.__level == 0:
            raise AttributeError
        return FakeModule(self.__name__+'.'+attr, self.__level-1)

    def __cmp__(self, other):
        if not hasattr(other, '___name__'):
            return -1
        return cmp(self.__name__, other.__name__)

def fakeOut(modname):
    modpath = modname.split('.')
    prevmod = None
    for m in range(len(modpath)):
        mp = '.'.join(modpath[:m+1])
        nm = FakeModule(mp, 4)
        if prevmod:
            setattr(prevmod, modpath[m], nm)
        sys.modules[mp] = nm
        prevmod = nm

#fakeOut("gnome.ui")
#fakeOut("pygtk")
#fakeOut("gtk")
#fakeOut("wxPython.wx")
#fakeOut('wx')
sys.modules["zope.interface._zope_interface_coptimizations"] = None

## HACK: This is a nasty one! Replace TypeType with (TypeType,
## InterfaceClass), and dir with something that makes Interfaces look like 
## classes so epydoc will try to document Interfaces.
from zope.interface.interface import InterfaceClass, Method, Attribute
import types
types.TypeType = (types.TypeType, InterfaceClass)
_marker = object()
def epydir(obj=_marker, dir=dir):
    if obj is _marker:
        return sys._getframe(1).f_locals.keys()
    elif isinstance(obj, InterfaceClass):
        return obj.names(all=True)
    else:
        return dir(obj)
import __builtin__
__builtin__.dir = epydir

# initial twisted
from twisted.python import reflect, util
#from twisted.internet import reactor
# epydoc
import epydoc
assert epydoc.__version__[0] == '2', "You need epydoc 2.x!"
from epydoc.cli import cli
from epydoc.html import HTMLFormatter, _write_if_nonempty
from epydoc import uid
import epydoc.html

# HACK: More zope.interface hackery -- zope.interface.interface.Methods are
# methods too!
is_method_orig = uid.ObjectUID.is_method
def is_method(self):
    return is_method_orig(self) or isinstance(self._obj, Method)
uid.ObjectUID.is_method = is_method
is_routine_orig = uid.ObjectUID.is_routine
def is_routine(self):
    return is_routine_orig(self) or isinstance(self._obj, Method)
uid.ObjectUID.is_routine = is_routine
_findname_orig = uid.ObjectUID._findname
def _findname(self):
    if isinstance(self._obj, Method):
        return '%s.%s' % (self.cls(), self._obj.__name__)
    else:
        return _findname_orig(self)
uid.ObjectUID._findname = _findname
cls_orig = uid.ObjectUID.cls
def cls(self):
    if isinstance(self._obj, Method):
        return uid.ObjectUID(self._obj.interface)
    else:
        return cls_orig(self)
uid.ObjectUID.cls = cls
module_orig = uid.ObjectUID.module
def module(self):
    if isinstance(self._obj, Method):
        return uid.ObjectUID(self._obj.interface).module()
    else:
        return module_orig(self)
uid.ObjectUID.module = module

make_uid_orig = uid.make_uid
def make_uid(obj, base_uid=None, shortname=None):
    if isinstance(obj, Method):
        key = (id(obj), id(obj.interface))
        obj_uid = uid._object_uids.get(key)
        if obj_uid is not None: return obj_uid
        obj_uid = uid.ObjectUID(obj)
        uid._object_uids[key] = obj_uid
        return obj_uid
    else:
        return make_uid_orig(obj, base_uid, shortname)
uid.make_uid = make_uid

# HACK: Don't append -module and -class to the filenames, and generate
# redirecty-files for all methods.

class TwistedHTMLFormatter(HTMLFormatter):
    def _uid_to_filename(self, uid):
        # Enforce same restrictions as HTMLFormatter._uid_to_filename for sanity
        # checking
        assert uid.is_module() or uid.is_class(), 'Bad UID type: %r' % (uid,)
        return uid.name() + '.html'
        
    def _uid_to_uri(self, uid):
        if uid.is_module() or uid.is_class():
            return uid.name() + '.html'

        parent = uid.parent()
        if parent is None:
            return uid.name() + '.html'

        return parent.name() + '.html#' + uid.shortname()

    def _method_to_html(self, uid):
        """
        Dodgy redirect hack.
        """
        str = ('<html><head>\n'
               '<meta http-equiv=refresh content="0; url=%s#%s">\n'
               '</head></html>\n')
        str = str % (self._uid_to_uri(uid.parent()), uid.shortname())
        return str

    def write(self, directory=None, progress_callback=None):
        HTMLFormatter.write(self, directory, progress_callback)
        
        # Write method redirectors
        self._write_method_redirects(directory)

    def _write_method_redirects(self, directory):
        import os.path
        seen = {}
        for uid, doc in self._docmap.data.iteritems():
            if uid.is_method() or uid.is_function():
                if uid.name() in seen: continue
                seen[uid.name()] = 1
                filename = os.path.join(directory, uid.name() + '.html')
                #assert not os.path.exists(filename), filename
                s = self._method_to_html(uid)
                open(filename, 'w').write(s)

    # fix barf on non-ASCII problem
    def _write_func_details(self, public, private, container, functions,
                        heading='Function Details'):

        docmap = self._docmap
        functions = [f for f in functions if docmap.has_key(f.target())]

        cuid = container.uid()
        if cuid.is_class():
            # Filter out inherited methods (their details docs are
            # listed under the class that defines them):
            functions = [f for f in functions
                         if f.target().cls() == cuid]

            # Filter out methods that don't define or inherit docstrings;
            # they are just listed in the summary table.
            functions = [f for f in functions
                         if docmap.documented_ancestor(f.target())]
        else:
            # Filter out functions that don't define docstrings; they
            # are just listed in the summary table.
            functions = [f for f in functions
                         if docmap[f.target()].has_docstring()]

        # If there are no functions left, then just return.
        if len(functions) == 0: return
        
        # Divide the functions into groups
        groups = container.by_group(functions)

        # Write the table header
        header = self._table_header(heading, 'details')+'</table>\n'
        _write_if_nonempty(public, private, functions, header)

        # Write an entry for each function.
        for function in functions:
            str = self._func_details_entry(function, container)
            private.write("".join([n for n in str if ord(n) < 128]))
            if function.target().is_public(): public.write(str)

        # Write the table footer
        _write_if_nonempty(public, private, functions, '<br />\n\n')

    # when doing non-full builds we need to fake epydoc in to thinking that
    # all twisted modules are being documented so that the html links
    # to the modules that aren't being documented get generated correctly
    def _documented(self, uid):
        value = HTMLFormatter._documented(self, uid)
        if not document_all:
            if not value:
                try:
                    if uid._name.startswith('twisted.'): #ha ha sucker
                        return True
                except:
                    pass
        return value

epydoc.html.HTMLFormatter = TwistedHTMLFormatter

# HACK: Only document stuff that we _tell_ you to document, you stupid
# &#@&!#@

from epydoc import objdoc

# HACK: objdoc directly imports make_uid, so our monkeypatch to make_uid needs
# to happen here too:
objdoc.make_uid = make_uid

# HACK: add dummy im_func attr to Method to make epydoc happy
Method.im_func = property(lambda s: s)

# HACK: teach inspect.getargspec how to extract info from Methods
import inspect
getargspec_orig = inspect.getargspec
def getargspec(func):
    if isinstance(func, Method):
        spec = func.getSignatureInfo()
        defaults = [spec['optional'][arg] 
                    for arg in spec['positional'] 
                    if arg in spec['optional']]
        return (spec['positional'], spec['varargs'], spec['kwargs'], defaults)
    else:
        return getargspec_orig(func)
inspect.getargspec = getargspec

# HACK: Make FuncDoc DTRT with Methods
_init_signature_orig = objdoc.FuncDoc._init_signature
# This one is for epydoc CVS
def _init_signature(self, func):
    if isinstance(func, Method):
        docstring = objdoc._getdoc(func)
        self._init_signature_from_argspec(*inspect.getargspec(func))
        return docstring
    else:
        return _init_signature_orig(self, func)
objdoc.FuncDoc._init_signature = _init_signature

# This one is for epydoc 2.1
_init_builtin_signature_orig = objdoc.FuncDoc._init_builtin_signature
def _init_builtin_signature(self, func):
    if isinstance(func, Method):
        _init_signature_orig(self, func)
        return False
    else:
        return _init_builtin_signature_orig(self, func)
objdoc.FuncDoc._init_builtin_signature = _init_builtin_signature


### NRY 24 Jun 2005
# make attribute introspection work
_lookup_class_field_orig = objdoc._lookup_class_field

def _lookup_class_field(cls, field, base_order=None):
    result = _lookup_class_field_orig(cls, field, base_order)

    if result[0] ==  '<Not Accessible>':
        if isinstance(cls, InterfaceClass):
            target = cls[field]
            repr = result[0]
            
            if isinstance(target, (Attribute, Method)):
                repr = target.getDoc()
                
            result = (repr, result[1])

    return result

    pass
objdoc._lookup_class_field = _lookup_class_field


# HACK: Another "only doc what we tell you". We don't want epydoc to
# automatically recurse into subdirectories: "twisted"'s presence was
# causing "twisted/test" to be docced, even thought we explicitly
# didn't put any twisted/test in our modnames.

from epydoc import imports
orig_find_modules = imports.find_modules

import re

def find_modules(dirname):
    if not os.path.isdir(dirname): return []
    found_init = 0
    modules = {}
    dirs = []

    # Search for directories & modules, and check for __init__.py.
    # Don't include duplicates (like foo.py and foo.pyc), and give
    # precedance to the .py files.
    for file in os.listdir(dirname):
        filepath = os.path.join(dirname, file)
        if os.path.isdir(filepath): dirs.append(filepath)
        elif not re.match(r'\w+.py.?', file):
            continue # Ignore things like ".#foo.py" or "a-b.py"
        elif file[-3:] == '.py':
            modules[file] = os.path.join(dirname, file)
            if file == '__init__.py': found_init = 1
        elif file[-4:-1] == '.py':
            modules.setdefault(file[:-1], file)
            if file[:-1] == '__init__.py': found_init = 1
    modules = modules.values()

    # If there was no __init__.py, then this isn't a package
    # directory; return nothing.
    if not found_init: return []

    # Recurse to the child directories.
    # **twisted** here's the change: commented next line out
    for d in dirs:
        if 'tests' in d or 'fltests' in d:
            continue
        modules += find_modules(d)
    return modules


imports.find_modules = find_modules



# Now, set up the list of modules for epydoc to document
modnames = []
def addMod(arg, path, files):
    if 'test' in files:
        files.remove('test')
    if 'topfiles' in files:
        files.remove('topfiles')
    for fn in files:
        file = os.path.join(path, fn).replace('%s__init__'%os.sep, '')
        if file[-3:] == '.py':
            modName = file[:-3].replace(os.sep,'.')
            try:
                #print 'pre-loading', modName
                reflect.namedModule(modName)
            except ImportError:
                print 'import error:', modName
            except:
                print 'other error:', modName
            else:
                modnames.append(modName)

document_all = True # are we doing a full build?
names = ['zope',] #default, may be overriden below

#get list of modules/pkgs on cmd-line
try:
    i = sys.argv.index("--modules")
except:
    pass
else:
    names = sys.argv[i+1:]
    document_all = False
    sys.argv[i:] = []
    #sanity check on names
    #for i in range(len(names)):
    #    try:
    #        j = names[i].rindex('twisted/') 
    #    except:
    #        raise SystemExit, 'You can only specify twisted modules or packages'
    #    else:
    #        #strip off any leading directories before the 'twisted/'
    #         #dir. this makes it easy to specify full paths, such as
    #         #from TwistedEmacs
    #         names[i] = names[i][j:]

    old_out_dir = "html"
    #if -o was specified, we need to change it to point to a tmp dir
    #otherwise add our own -o option
    try:
        i = sys.argv.index('-o')
        old_out_dir = sys.argv[i+1]
        try:
            os.mkdir(tmp_dir)
        except OSError:
            pass
        sys.argv[i+1] = tmp_dir
    except ValueError:
        sys.argv[1:1] = ['-o', tmp_dir]

osrv = sys.argv
sys.argv=["IGNORE"]
im = __import__
__builtins__.__import__ = myimport

for name in names:
    if name.endswith(".py"):
        # turn it in to a python module name
        name = name[:-3].replace(os.sep, ".")
        try:
            reflect.namedModule(name)
        except ImportError:
            print 'import error:', name
        except Exception, e:
            print 'other error:', name, e
        else:
            modnames.append(name)
    else: #assume it's a dir
        os.path.walk(name, addMod, None)

__builtins__.__import__ = im
sys.argv = osrv




if 'twisted.test' in modnames:
    modnames.remove('twisted.test')

##if 'twisted' in modnames:
##    modnames.remove('twisted')

sys.argv.extend(modnames)

# Make it easy to profile epyrun
if 0:
    import profile
    profile.run('cli()', 'epyrun.prof')
else:
    cli()

# used when doing partial builds to move the new files
# out of the tmp dir and in to the real output dir.
# only does "twisted." files since the others (index.html and such)
# won't be right when not doing full builds.
def moveFilesOut(arg, dirname, fnames):
    for fn in fnames:
        if fn.startswith('twisted.'):
            shutil.move('%s%s%s' % (tmp_dir, os.sep, fn), old_out_dir)
        
if not document_all:
    print "Updating files in %s" % old_out_dir
    #move the right html files in to place
    os.path.walk(tmp_dir, moveFilesOut, None)
    #clean up
    shutil.rmtree(tmp_dir)

print 'Done!'