path: root/tools/class2rst.py

#!/usr/bin/python
#
# Copyright (C) 2012 Red Hat, Inc.  All rights reserved.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
#
# Authors: Jan Safranek <jsafrane@redhat.com>
#

import os;
import pywbem;
import optparse
import re
import cgi
import sys

class HtmlExporter(object):
    
    def __init__(self, cliconn):
        self.classcache = {}
        self.cliconn = cliconn
        # original list of classes
        self.classes = []
        # set of all classes to print, i.e. incl. all parents
        self.queue = set()
        self.file = None

    def link(self, classname, attributename = ""):
        if attributename:
            link = classname + "-" + attributename
        else:
            link = classname
        link = link.replace("_","-")
        return link
        
    def print_escaped(self, string, prefix = ""):
        # replace \n with prefixes
        lines = string.split("\\n")
        for line in lines:
            print >>self.file, prefix + line
            print >>self.file, ""
    
    def load_class(self, classname):
        if classname in self.classcache:
            return self.classcache[classname]

        c = self.cliconn.GetClass(classname)
        self.classcache[classname] = c
        return c

    def source_class(self, c, param):
        """
            Find a class where a CIMMethod or CIMProperty is first defined.
            Start at class c and inspect all parents.
        """

        while True:

            if isinstance(param, pywbem.CIMMethod):
                if not c.methods.has_key(param.name):
                    break
            else:
                if not c.properties.has_key(param.name):
                    break

            if not c.superclass:
                # we're at the top class
                return c.classname
                
            parent = c
            c = self.load_class(c.superclass)
        return parent.classname

    def display_type(self, param):
        """
            Return displayable type of given parameter.
            It adds [] if it's array and class name of referenced classes.
        """
        url = False
        if param.reference_class:
            ptype = param.reference_class
            url = True
        else:
            ptype = param.type
        if param.is_array:
            ptype = ptype + "[]"
        if url:
            ptype = ":ref:`%s <%s>`" % (ptype, self.link(ptype))
        else:
            ptype = "``" + ptype + "``"
        return ptype

    def print_parameters(self, params):
        """
            Print table of method parametes.
        """
        function_indent = " "*4
        if not params:
            print >>self.file, "*None*"
            return

        for p in params.values():
            param_indent = " "*8
            direction = set()
            if p.qualifiers.has_key("Out"):
                direction.add("*OUT*")
            if p.qualifiers.has_key("In"):
                if p.qualifiers["In"].value:
                    direction.add("*IN*")
            if not direction:
                direction.add("*IN*")
            direction = ", ".join(sorted(direction))

            print >>self.file, param_indent + "%s %s **%s**" % (direction, self.display_type(p), p.name)
            self.print_qualifiers(p.qualifiers.values(), param_indent+ " "*4)
            print >>self.file, param_indent
        print >>self.file, function_indent

    def print_prototype(self, method):
        """ Print function prototype """
        self.file.write("``" + method.return_type + "`` ")
        self.file.write("**" + method.name + "** (")
        params = []
        for p in method.parameters.values():
            params.append((self.display_type(p) + " " + p.name))
        self.file.write(", ".join(params))
        self.file.write("\n")
        
    def print_table(self, col1, col2, indent):
        """
            Print table with two columns.
        """
        len1 = max(max(map(len, col1)), len("ValueMap"))
        len2 = max(max(map(len, col2)), len("Values"))
        separator = "="*len1 + " " + "="*len2
        print >>self.file, indent + separator
        print >>self.file, indent + format("ValueMap", str(len1)) + " " + format("Values", str(len2))
        print >>self.file, indent + separator
        for i in range(len(col1)):
            print >>self.file, indent + format(col1[i], str(len1)) + " " + format(col2[i], str(len2))
        print >>self.file, indent + separator

    def print_qualifiers(self, qualifiers, indent):
        """
            Print content of table of qualifiers.
            Only Deprecated, Description, Values and ValueMap are recognized.
        """
        deprecated = ""
        values = None
        maps = None
        for q in sorted(qualifiers):
            if q.name == "Deprecated":
                deprecated = "**Deprecated!** "
            if q.name == "Description":
                if deprecated:
                    print >>self.file, indent + deprecated
                self.print_escaped(q.value, indent)
            if q.name == "Values":
                values = q.value
            if q.name == "ValueMap":
                maps = q.value
        print >>self.file, indent
        if maps and values:
            self.print_table(maps, values, indent)
            print >>self.file, indent

    def compare_properties(self, p1, p2):
        """
            Compare two properties. Only Name and Description are checked.
        """
        if p1.name != p2.name:
            return False
        d1 = p1.qualifiers.get("Description", None)
        d2 = p2.qualifiers.get("Description", None)
        if d1.value != d2.value:
            return False
        return True

    def print_keys(self, c):
        print >>self.file, "Key properties"
        print >>self.file, "^^^^^^^^^^^^^^"
        print >>self.file, ""
        for prop in c.properties.values():
            if prop.qualifiers.has_key('Key'):
                src = self.source_class(c, prop)
                link = self.link(src, prop.name)
                print >>self.file, "| :ref:`%s <%s>`" % (prop.name, link)
        print >>self.file, ""

    def print_class(self, c):
        """
            Print one class, inc. header.
        """
        parent = None
        if c.superclass:
            parent = self.load_class(c.superclass)
            print >>self.file, "Subclass of :ref:`%s <%s>`" % (c.superclass, self.link(c.superclass))
            print >>self.file, ""

        description = c.qualifiers.get("Description", None)
        if not description:
            description = parent.qualifiers.get("Description", None)
        if description:
            self.print_escaped(description.value, "")
        print >>self.file, ""

        self.print_keys(c)

        local_props = []
        inherited_props = []
        for name in sorted(c.properties.keys()):
            if parent and parent.properties.has_key(name):
                inherited_props.append(c.properties[name])
                if not self.compare_properties(c.properties[name], parent.properties[name]):
                    # the property was overridden
                    local_props.append(c.properties[name])
            else:
                local_props.append(c.properties[name])

        local_methods = []
        inherited_methods = []
        for name in sorted(c.methods.keys()):
            if parent and parent.methods.has_key(name):
                inherited_methods.append(c.methods[name])
                if not self.compare_properties(c.methods[name], parent.methods[name]):
                    # the property was overridden
                    local_methods.append(c.methods[name])
            else:
                local_methods.append(c.methods[name])

        print >>self.file, "Local properties"
        print >>self.file, "^^^^^^^^^^^^^^^^"
        print >>self.file, ""
        if local_props:
            for prop in local_props:
                prop_link = self.link(c.classname, prop.name)
                print >>self.file, ".. _%s:" % (prop_link)
                print >>self.file, ""
                print >>self.file, "%s **%s**" % (self.display_type(prop), prop.name)
                print >>self.file, ""
                self.print_qualifiers(prop.qualifiers.values(), " "*4)
                print >>self.file, ""
        else:
            print >>self.file, "*None*"
            print >>self.file, ""

        print >>self.file, "Local methods"
        print >>self.file, "^^^^^^^^^^^^^"
        print >>self.file, ""
        if local_methods:
            for m in local_methods:
                link = self.link(c.classname, m.name)
                print >>self.file, "    .. _%s:" % (link)
                print >>self.file, ""
                self.print_prototype(m)
                print >>self.file, ""
                self.print_qualifiers(m.qualifiers.values(), " "*4)
                print >>self.file, "    **Parameters**"
                print >>self.file, "    "
                self.print_parameters(m.parameters)
                print >>self.file, "    "
        else:
            print >>self.file, "*None*"
            print >>self.file, ""

        print >>self.file, "Inherited properties"
        print >>self.file, "^^^^^^^^^^^^^^^^^^^^"
        print >>self.file, ""
        if inherited_props:
            for p in inherited_props:
                src = self.source_class(c, p)
                link = self.link(src, p.name)
                print >>self.file, "| %s :ref:`%s <%s>`" % (self.display_type(p), p.name, link)
            print >>self.file, ""
        else:
            print >>self.file, "*None*"
            print >>self.file, ""

        print >>self.file, "Inherited methods"
        print >>self.file, "^^^^^^^^^^^^^^^^^"
        print >>self.file, ""
        if inherited_methods:
            for m in inherited_methods:
                src = self.source_class(c, m)
                link = self.link(src, m.name)
                print >>self.file, "| :ref:`%s <%s>`" % (m.name, link)
            print >>self.file, ""
        else:
            print >>self.file, "*None*"
            print >>self.file, ""


    def print_file(self, filename):
        f = open(filename, "r")
        data = f.read()
        self.file.write(data)
        f.close()

    def print_page(self, c, header, footer):
        print "exporting ", c.classname
        self.file = open(c.classname + ".rst", "w")
        print >>self.file, ".. _%s:" % self.link(c.classname)
        print >>self.file, ""
        print >>self.file, c.classname
        print >>self.file, "-"*len(c.classname)
        print >>self.file, ""
#        if header:
#            self.print_file(header)
        self.print_class(c)
#        if footer:
#            self.print_file(footer)
        self.file.close()
        
    def add_class(self, classname):
        self.classes.append(classname)
        print "adding", classname
        self.queue.add(classname)
        # add all parents
        c = self.load_class(classname)
        parentname = c.superclass
        while parentname:
            if parentname in self.queue:
                break
            print "adding", parentname
            self.queue.add(parentname)
            c = self.load_class(parentname)
            parentname = c.superclass

    def export(self, header=None, footer=None):
        """
            Print everything, i.e. index.rst + all classes + all their parents.
        """
        # remove duplicate classes from the queue (and sort them)
        self.queue = sorted(self.queue)
        self.print_tree_rst(header, footer)
        self.print_index_rst(header, footer)
        while self.queue:
            c = self.queue.pop()
            self.print_page(self.load_class(c), header, footer)

    def _do_print_tree(self, name, subtree, level):
        nbsp=" |nbsp| "
        if level:
            print >>self.file, "|    "  + ("\\|"+nbsp*7)*(level-1) + "\\|---",
        else:
            print >>self.file, "|",
        if name in self.classes:
            print >>self.file, "\*",
        link = self.link(name)
        print >>self.file, ":ref:`%s <%s>`" % (name, link)
        for n in subtree.keys():
            self._do_print_tree(n, subtree[n], level+1)

    def print_tree(self):
        """
            Create inheritance tree of classes.
        """
        # hash classname -> list of hash of (direct) sublasses 
        subclasses = {}
        # hash classname -> nr. of its parents
        parents = {}
        # initialize the hash
        for cname in self.queue:
            subclasses[cname] = {}
            parents[cname] = 0

        # fill the hash
        for cname in self.queue:
            c = self.load_class(cname)
            if c.superclass:
                subclasses[c.superclass][cname] = subclasses[cname]
                parents[cname] += 1

        print >>self.file, ".. |nbsp| unicode:: 0xA0"
        print >>self.file, "    :trim:"
        print >>self.file, ""
        # print all top classes
        for cname in self.queue:
            if parents[cname] == 0:
                self._do_print_tree(cname, subclasses[cname], 0)

    def print_index(self):
        """
            Create table of content.
        """
        # hash classname -> list of hash of (direct) sublasses 
        print >>self.file, ".. toctree::"
        print >>self.file, "    :maxdepth: 1"
        print >>self.file, ""
        # print all top classes
        for cname in self.queue:
            print >>self.file, "    " + cname


    def print_tree_rst(self, header, footer):
        print "exporting tree"
        self.file = open("tree.rst", "w")
        print >>self.file, "Inheritance tree"
        print >>self.file, "================"
        print >>self.file, ""

        self.print_tree()
        self.file.close()

    def print_index_rst(self, header, footer):
        print "exporting index"
        self.file = open("index.rst", "w")
        if header:
            self.print_file(header)
        self.print_index()
        if footer:
            self.print_file(footer)
        self.file.close()

description = """
Generate RST documentation for given CIM classes. The tool connects to specified CIMOM
and reads class definition from there. It generates separate RST file for each class
specified on command line and for all it's parents.

The tool also generates tree.rst with inheritance tree and index.rst with table of content.

The index.rst will optionally contain header and/or footer. Both must be valid
RST code snippets and will be inserted just at the beginning or at the end of the file.

Use Sphinx to generate html documentation from the RST files.
"""

parser = optparse.OptionParser(usage="usage: %prog [options] classname [classname ...]", description=description)
parser.add_option('-u', '--url', action='store', dest='addr', default='https://localhost:5989', help='URL of CIM server, default: https://localhost:5989')
parser.add_option('-U', '--user', action='store', dest='user', default=None, help='CIM user name')
parser.add_option('-P', '--password', action='store', dest='password', default=None, help='CIM password')
parser.add_option('-H', '--header', action='store', dest='header', default=None, help='File with HTML page header')
parser.add_option('-F', '--footer', action='store', dest='footer', default=None, help='File with HTML page footer')

(options, args) = parser.parse_args()

cliconn = pywbem.WBEMConnection(options.addr, (options.user, options.password))
exporter = HtmlExporter(cliconn)
for c in args:
    exporter.add_class(c)
exporter.export(options.header, options.footer)