#!/usr/bin/env python

#see license.txt for license details

#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/tools/docco/docpy.py

"""Generate documentation from live Python objects.

This is an evolving module that allows to generate documentation

for python modules in an automated fashion. The idea is to take

live Python objects and inspect them in order to use as much mean-

ingful information as possible to write in some formatted way into

different types of documents.

In principle a skeleton captures the gathered information and

makes it available via a certain API to formatters that use it

in whatever way they like to produce something of interest. The

API allows for adding behaviour in subclasses of these formatters,

such that, e.g. for certain classes it is possible to trigger

special actions like displaying a sample image of a class that

represents some graphical widget, say.

Type the following for usage info:

  python docpy.py -h

"""

# Much inspired by Ka-Ping Yee's htmldoc.py.

# Needs the inspect module.

# Dinu Gherman

__version__ = '0.8'

import sys, os, re, types, getopt, copy, time

from reportlab import isPy3

from reportlab.pdfgen import canvas

from reportlab.lib import colors

from reportlab.lib.units import inch, cm

from reportlab.lib.pagesizes import A4

from reportlab.lib import enums

from reportlab.lib.enums import TA_CENTER, TA_LEFT

from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle

from reportlab.platypus.flowables import Flowable, Spacer

from reportlab.platypus.paragraph import Paragraph

from reportlab.platypus.flowables \

     import Flowable, Preformatted,Spacer, Image, KeepTogether, PageBreak

from reportlab.platypus.tableofcontents import TableOfContents

from reportlab.platypus.xpreformatted import XPreformatted

from reportlab.platypus.frames import Frame

from reportlab.platypus.doctemplate \

     import PageTemplate, BaseDocTemplate

from reportlab.platypus.tables import TableStyle, Table

import inspect

####################################################################

#

# Stuff needed for building PDF docs.

#

####################################################################

def mainPageFrame(canvas, doc):

    "The page frame used for all PDF documents."

    canvas.saveState()

    pageNumber = canvas.getPageNumber()

    canvas.line(2*cm, A4[1]-2*cm, A4[0]-2*cm, A4[1]-2*cm)

    canvas.line(2*cm, 2*cm, A4[0]-2*cm, 2*cm)

    if pageNumber > 1:

        canvas.setFont('Times-Roman', 12)

        canvas.drawString(4 * inch, cm, "%d" % pageNumber)

        if hasattr(canvas, 'headerLine'): # hackish

            headerline = ' \215 '.join(canvas.headerLine) # bullet

            canvas.drawString(2*cm, A4[1]-1.75*cm, headerline)

    canvas.setFont('Times-Roman', 8)

    msg = "Generated with reportlab.lib.docpy. See http://www.reportlab.com!"

    canvas.drawString(2*cm, 1.65*cm, msg)

    canvas.restoreState()

class MyTemplate(BaseDocTemplate):

    "The document template used for all PDF documents."

    _invalidInitArgs = ('pageTemplates',)

    def __init__(self, filename, **kw):

        frame1 = Frame(2.5*cm, 2.5*cm, 15*cm, 25*cm, id='F1')

        self.allowSplitting = 0

        BaseDocTemplate.__init__(self, filename, **kw)

        self.addPageTemplates(PageTemplate('normal', [frame1], mainPageFrame))

    def afterFlowable(self, flowable):

        "Takes care of header line, TOC and outline entries."

        if flowable.__class__.__name__ == 'Paragraph':

            f = flowable

            name7 = f.style.name[:7]

            name8 = f.style.name[:8]

            # Build a list of heading parts.

            # So far, this is the *last* item on the *previous* page...

            if name7 == 'Heading' and not hasattr(self.canv, 'headerLine'):

                self.canv.headerLine = []

            if name8 == 'Heading0':

                self.canv.headerLine = [f.text] # hackish

            elif name8 == 'Heading1':

                if len(self.canv.headerLine) == 2:

                    del self.canv.headerLine[-1]

                elif len(self.canv.headerLine) == 3:

                    del self.canv.headerLine[-1]

                    del self.canv.headerLine[-1]

                self.canv.headerLine.append(f.text)

            elif name8 == 'Heading2':

                if len(self.canv.headerLine) == 3:

                    del self.canv.headerLine[-1]

                self.canv.headerLine.append(f.text)

            if name7 == 'Heading':

                # Register TOC entries.

                headLevel = int(f.style.name[7:])

                self.notify('TOCEntry', (headLevel, flowable.getPlainText(), self.page))

                # Add PDF outline entries.

                c = self.canv

                title = f.text

                key = str(hash(f))

                try:

                    if headLevel == 0:

                        isClosed = 0

                    else:

                        isClosed = 1

                    c.bookmarkPage(key)

                    c.addOutlineEntry(title, key, level=headLevel,

                                      closed=isClosed)

                except ValueError:

                    pass

####################################################################

#

# Utility functions (Ka-Ping Yee).

#

####################################################################

def htmlescape(text):

    "Escape special HTML characters, namely &, <, >."

    return text.replace('&','&amp;').replace('<','&lt;').replace('>','&gt;')

def htmlrepr(object):

    return htmlescape(repr(object))

def defaultformat(object):

    return '=' + htmlrepr(object)

def getdoc(object):

    result = inspect.getdoc(object)

    if not result:

        try:

            result = inspect.getcomments(object)

        except:

            pass

    return result and result.rstrip() + '\n' or ''

def reduceDocStringLength(docStr):

    "Return first line of a multiline string."

    return docStr.split('\n')[0]

####################################################################

#

# More utility functions

#

####################################################################

def makeHtmlSection(text, bgcolor='#FFA0FF'):

    """Create HTML code for a section.

    This is usually a header for all classes or functions.

u    """

    text = htmlescape(text.expandtabs())

    result = []

    result.append("""<TABLE WIDTH="100\\%" BORDER="0">""")

    result.append("""<TR><TD BGCOLOR="%s" VALIGN="CENTER">""" % bgcolor)

    result.append("""<H2>%s</H2>""" % text)

    result.append("""</TD></TR></TABLE>""")

    result.append('')

    return '\n'.join(result)

def makeHtmlSubSection(text, bgcolor='#AAA0FF'):

    """Create HTML code for a subsection.

    This is usually a class or function name.

    """

    text = htmlescape(text.expandtabs())

    result = []

    result.append("""<TABLE WIDTH="100\\%" BORDER="0">""")

    result.append("""<TR><TD BGCOLOR="%s" VALIGN="CENTER">""" % bgcolor)

    result.append("""<H3><TT><FONT SIZE="+2">%s</FONT></TT></H3>""" % text)

    result.append("""</TD></TR></TABLE>""")

    result.append('')

    return '\n'.join(result)

def makeHtmlInlineImage(text):

    """Create HTML code for an inline image.

    """

    return """<IMG SRC="%s" ALT="%s">""" % (text, text)

####################################################################

#

# Core "standard" docpy classes

#

####################################################################

class PackageSkeleton0:

    """A class collecting 'interesting' information about a package."""

    pass # Not yet!

class ModuleSkeleton0:

    """A class collecting 'interesting' information about a module."""

    def __init__(self):

        # This is an ad-hoc, somewhat questionable 'data structure',

        # but for the time being it serves its purpose and is fairly

        # self-contained.

        self.module = {}

        self.functions = {}

        self.classes = {}

    # Might need more like this, later.

    def getModuleName(self):

        """Return the name of the module being treated."""

        return self.module['name']

    # These inspect methods all rely on the inspect module.

    def inspect(self, object):

        """Collect information about a given object."""

        self.moduleSpace = object

        # Very non-OO, left for later...

        if inspect.ismodule(object):

            self._inspectModule(object)

        elif inspect.isclass(object):

            self._inspectClass(object)

        elif inspect.ismethod(object):

            self._inspectMethod(object)

        elif inspect.isfunction(object):

            self._inspectFunction(object)

        elif inspect.isbuiltin(object):

            self._inspectBuiltin(object)

        else:

            msg = "Don't know how to document this kind of object."

            raise TypeError(msg)

    def _inspectModule(self, object):

        """Collect information about a given module object."""

        name = object.__name__

        self.module['name'] = name

        if hasattr(object, '__version__'):

            self.module['version'] = object.__version__

        cadr = lambda list: list[1]

        modules = list(map(cadr, inspect.getmembers(object, inspect.ismodule)))

        classes, cdict = [], {}

        for key, value in inspect.getmembers(object, inspect.isclass):

            if (inspect.getmodule(value) or object) is object:

                classes.append(value)

                cdict[key] = cdict[value] = '#' + key

        functions, fdict = [], {}

        for key, value in inspect.getmembers(object, inspect.isroutine):

            #if inspect.isbuiltin(value) or inspect.getmodule(value) is object:

            functions.append(value)

            fdict[key] = '#-' + key

            if inspect.isfunction(value): fdict[value] = fdict[key]

        for c in classes:

            for base in c.__bases__:

                key, modname = base.__name__, base.__module__

                if modname != name and modname in sys.modules:

                    module = sys.modules[modname]

                    if hasattr(module, key) and getattr(module, key) is base:

                        if key not in cdict:

                            cdict[key] = cdict[base] = modname + '.txt#' + key

##        doc = getdoc(object) or 'No doc string.'

        doc = getdoc(object)

        self.module['doc'] = doc

        if modules:

            self.module['importedModules'] = [m.__name__ for m in modules]

        if classes:

            for item in classes:

                self._inspectClass(item, fdict, cdict)

        if functions:

            for item in functions:

                self._inspectFunction(item, fdict, cdict)

    def _inspectClass(self, object, functions={}, classes={}):

        """Collect information about a given class object."""

        name = object.__name__

        bases = object.__bases__

        results = []

        if bases:

            parents = []

            for base in bases:

                parents.append(base)

        self.classes[name] = {}

        if bases:

            self.classes[name]['bases'] = parents

        methods, mdict = [], {}

        for key, value in inspect.getmembers(object, inspect.ismethod):

            methods.append(value)

            mdict[key] = mdict[value] = '#' + name + '-' + key

        if methods:

            if 'methods' not in self.classes[name]:

                self.classes[name]['methods'] = {}

            for item in methods:

                self._inspectMethod(item, functions, classes, mdict, name)

##        doc = getdoc(object) or 'No doc string.'

        doc = getdoc(object)

        self.classes[name]['doc'] = doc

    def _inspectMethod(self, object, functions={}, classes={}, methods={}, clname=''):

        """Collect information about a given method object."""

        self._inspectFunction(object.__func__, functions, classes, methods, clname)

    def _inspectFunction(self, object, functions={}, classes={}, methods={}, clname=''):

        """Collect information about a given function object."""

        try:

            args, varargs, varkw, defaults = inspect.getargspec(object)

            argspec = inspect.formatargspec(

                args, varargs, varkw, defaults,

                defaultformat=defaultformat)

        except TypeError:

            argspec = '( ... )'

##        doc = getdoc(object) or 'No doc string.'

        doc = getdoc(object)

        if object.__name__ == '<lambda>':

            decl = [' lambda  ', argspec[1:-1]]

            # print '  %s' % decl

            # Do something with lambda functions as well...

            # ...

        else:

            decl = object.__name__

            if not clname:

                self.functions[object.__name__] = {'signature':argspec, 'doc':doc}

            else:

                theMethods = self.classes[clname]['methods']

                if object.__name__ not in theMethods:

                    theMethods[object.__name__] = {}

                theMethod = theMethods[object.__name__]

                theMethod['signature'] = argspec

                theMethod['doc'] = doc

    def _inspectBuiltin(self, object):

        """Collect information about a given built-in."""

        print(object.__name__ + '( ... )')

    def walk(self, formatter):

        """Call event methods in a visiting formatter."""

        s = self

        f = formatter

        # The order is fixed, but could be made flexible

        # with one more template method...

        # Module

        modName = s.module['name']

        modDoc = s.module['doc']

        imported = s.module.get('importedModules', [])

        imported.sort()

        # f.indentLevel = f.indentLevel + 1

        f.beginModule(modName, modDoc, imported)

        # Classes

        f.indentLevel = f.indentLevel + 1

        f.beginClasses(list(s.classes.keys()))

        items = list(s.classes.items())

        items.sort()

        for k, v in items:

            cDoc = s.classes[k]['doc']

            bases = s.classes[k].get('bases', [])

            f.indentLevel = f.indentLevel + 1

            f.beginClass(k, cDoc, bases)

            # This if should move out of this method.

            if 'methods' not in s.classes[k]:

                s.classes[k]['methods'] = {}

            # Methods

            #f.indentLevel = f.indentLevel + 1

            f.beginMethods(list(s.classes[k]['methods'].keys()))

            items = list(s.classes[k]['methods'].items())

            items.sort()

            for m, v in items:

                mDoc = v['doc']

                sig = v['signature']

                f.indentLevel = f.indentLevel + 1

                f.beginMethod(m, mDoc, sig)

                f.indentLevel = f.indentLevel - 1

                f.endMethod(m, mDoc, sig)

            #f.indentLevel = f.indentLevel - 1

            f.endMethods(list(s.classes[k]['methods'].keys()))

            f.indentLevel = f.indentLevel - 1

            f.endClass(k, cDoc, bases)

            # And what about attributes?!

        f.indentLevel = f.indentLevel - 1

        f.endClasses(list(s.classes.keys()))

        # Functions

        f.indentLevel = f.indentLevel + 1

        f.beginFunctions(list(s.functions.keys()))

        items = list(s.functions.items())

        items.sort()

        for k, v in items:

            doc = v['doc']

            sig = v['signature']

            f.indentLevel = f.indentLevel + 1

            f.beginFunction(k, doc, sig)

            f.indentLevel = f.indentLevel - 1

            f.endFunction(k, doc, sig)

        f.indentLevel = f.indentLevel - 1

        f.endFunctions(list(s.functions.keys()))

        #f.indentLevel = f.indentLevel - 1

        f.endModule(modName, modDoc, imported)

        # Constants?!

####################################################################

#

# Core "standard" docpy document builders

#

####################################################################

class DocBuilder0:

    """An abstract class to document the skeleton of a Python module.

    Instances take a skeleton instance s and call their s.walk()

    method. The skeleton, in turn, will walk over its tree structure

    while generating events and calling equivalent methods from a

    specific interface (begin/end methods).

    """

    fileSuffix = None

    def __init__(self, skeleton=None):

        self.skeleton = skeleton

        self.packageName = None

        self.indentLevel = 0

    def write(self, skeleton=None):

        if skeleton:

            self.skeleton = skeleton

        self.skeleton.walk(self)

    # Event-method API, called by associated skeleton instances.

    # In fact, these should raise a NotImplementedError, but for now we

    # just don't do anything here.

    # The following four methods are *not* called by skeletons!

    def begin(self, name='', typ=''): pass

    def end(self): pass

    # Methods for packaging should move into a future PackageSkeleton...

    def beginPackage(self, name):

        self.packageName = name

    def endPackage(self, name):