source: topdoc/branches/xml_2014-03-31/src/topdoc/TopDoc.py @ 1534

#!/usr/bin/env python

'''autogenerate documentation of EPICS IOCs'''


import CmdReader
import CommandTable
import datetime
import os
import pprint           #@UnusedImport
import shutil
import SymbolTable
import sys
import traceback        #@UnusedImport
import Trove
import xmlTools
import utilities


SVN_ID = "$Id: TopDoc.py 1534 2014-04-01 16:52:56Z jemian $"


class TopDoc():
    '''
    TopDoc documents IOCs in an EPICS top-level directory
    '''
    config = None

    def __init__(self, config, keepAnalyses = True):
        '''
        Constructor
        '''
        self.config = config
        self.keepAnalyses = keepAnalyses
        self.project = None
        self.topContent = {}
        self.trove = Trove.Trove()

    def learn(self):
        '''
        Learn about this EPICS top-level directory.
        Store the results in self.topContent
        '''
        if self.config is None or 'rootDir' not in self.config:
            return None
        original_wd = os.getcwd()
        config_dict = {'config': self.config, 'iocBoot': {}}
        root = self.config['rootDir']
        for iocConfig in self.config['IOCs']:
            key = os.path.join(iocConfig['iocDir'], iocConfig['cmdFile'])
            bootDir = os.path.join(root, iocConfig['iocDir'])
            if os.path.exists( bootDir ):
                pwd = os.getcwd()
                utilities.chdir( bootDir )
                self.trove.addFile(iocConfig['cmdFile'], os.path.join(root, key))
                config_dict['iocBoot'][key] = self.addIOC(iocConfig)
                utilities.chdir( pwd )
        self.topContent = config_dict
        utilities.chdir( original_wd )

    def addIOC(self, config_dict):
        '''
        learn about this IOC

        :param config_dict: configuration of this IOC
        :return: dictionary of analyses
        '''
        tables = {
            'symbols' :         SymbolTable.Symbols(),
            'env' :             SymbolTable.Symbols(),
            'commands' :        CommandTable.Commands(),
            'includeFiles' :    SymbolTable.Symbols(),
            'databases' :       SymbolTable.Symbols(),
            'mounts' :          SymbolTable.Symbols(),
        }
        keys = tables.keys()
        tables['analyses'] = {}
        
        path = os.path.join(config_dict['iocDir'], config_dict['cmdFile'])
        utilities.logMessage("processing IOC: %s" % path)
        cr = CmdReader.CmdReader( config_dict['cmdFile'], tables )
        
        results = {}
        # command files, list avoids redundancy
        results['filenames'] = [(fname, v.absolute_filename) for fname, v in cr.cache_dbFile.items()]
        # databases
        #    this code does not capture ALL PV instances, motor for example
        #    results are available elsewhere
        #     pv_xref = {}
        #     for db in tables['databases'].table.values():
        #         for pv_name, pv_dict in db.items():
        #             pv_rtyp = pv_dict['RTYP']
        #             if pv_rtyp not in pv_xref:
        #                 pv_xref[pv_rtyp] = []
        #             pv_xref[pv_rtyp].append(pv_name)
        #     results['pv_rtyp'] = pv_xref
        # templates
        for item in keys:
            results[item] = tables[item].list
        if self.keepAnalyses:
            results['analyses'] = tables['analyses']
        return results

    def remember(self):
        '''
        try to get the full path to the various component files, amongst other things
        '''
        utilities.logMessage("remember")

    def write(self, targetDirectory):
        '''
        write what was discovered to file

        :param targetDirectory: directory in which to write the results
        :return: (string) name of html file written
        '''
        # TODO: major refactoring wanted, use ReST instead of XML
        # this implies using proper objects rather than dicts and lists
        # Why?  too cumbersome to preserve the analyses and propagate them to documentation via XML
        description = self.config['description']
        utilities.logMessage("learned about " + description)
        utilities.logMessage("writing results in: %s" % targetDirectory)
        # TODO: do something with other content found in docsDir
        # TODO: should write the analysis into docsDir
        # TODO: make the list of PVs and fields easily identifiable for bean counting
        if self.config['project'] is None:
            return
        xmlFile = os.path.join(targetDirectory, "%s.xml" % self.config['project'])
        writer = xmlTools.XmlWriter("TopDoc")
        writer.root.attrib['file_name'] = xmlFile
        writer.root.attrib['file_time'] = str(datetime.datetime.now())
        writer.root.attrib['creator'] = SVN_ID
        writer.addStructuredNode(writer.root, "top", {'name': description}, self.topContent)
        xsltFile = 'topdoc.xsl'
        writer.writeFile(xmlFile, xsltFile)
        utilities.logMessage("Wrote file: %s" % xmlFile)
        htmlFile = os.path.splitext(xmlFile)[0] + '.html'
        xmlTools.xsltproc(xmlFile, xsltFile, htmlFile)
        utilities.logMessage("Wrote file: %s" % htmlFile)
        shutil.copy(xsltFile, targetDirectory)
        utilities.logMessage("Wrote file: %s" % os.path.join(targetDirectory, xsltFile))
        return "%s.html" % self.config['project']

    def strip_analyses_tokens(self):
        '''remove the token analyses from the TopDoc object'''
        # deeply buried content:
        # self.topContent['iocBoot'][*]['analyses'][*][*]['tokens']
        for st_cmd in self.topContent['iocBoot'].values():
            for cmd_file in st_cmd['analyses'].values():
                for analysis in cmd_file.values():
                    del analysis['tokens']

def processConfigXml(xmlFile):
    '''
    process the contents of a given config.xml file
    '''
    utilities.logMessage("processing configuration file: %s" % os.path.abspath( xmlFile ))
    configuration = xmlTools.readConfigurationXML(xmlFile)
    reportDirectory = configuration['reportDirectory']
    
    html = xmlTools.XmlWriter("html")
    headNode = html.addStructuredNode(html.root, "head")
    html.addStructuredNode(headNode, "title", obj="IOCs")
    bodyNode = html.addStructuredNode(html.root, "body")
    html.addStructuredNode(bodyNode, "h1", obj="Documentation of IOCs")
    listNode = html.addStructuredNode(bodyNode, "ul")
    htmlFile = os.path.join(reportDirectory, 'index.html')
    if not os.path.exists(reportDirectory):
        os.makedirs(reportDirectory)
    
    for config in configuration['list']:
        topLevelDirExists = os.path.exists(config['rootDir'])
        msg = "Looking for: %s (exists=%s)" %(config['rootDir'], str(topLevelDirExists))
        utilities.logMessage(msg)
        if topLevelDirExists:
            pwd = os.getcwd()
            try:
                td = TopDoc(config, keepAnalyses=True)
                td.learn()
                #td.remember()
                utilities.chdir( pwd )
                td.strip_analyses_tokens()
                tdFile = td.write(reportDirectory)
                node = html.addStructuredNode(listNode, "li")
                desc = td.config['description']
                html.addStructuredNode(node, "a", {'href':tdFile}, obj=desc)
                html.writeFile(htmlFile)
                utilities.logMessage("Wrote file: %s" % htmlFile)
            except Exception, exc:
                msg = "problem while handling: %s" % config['rootDir']
                utilities.detailedExceptionLog(msg)
                traceback.print_exc()
            utilities.chdir( pwd )


def main():
    import argparse
    parser = argparse.ArgumentParser(prog='topdoc', 
                                     description=__doc__.strip())
    parser.add_argument('xmlFile', 
                        action='store', 
                        #nargs=1, 
                        help="XML configuration file")
    cmd_args = parser.parse_args()

    processConfigXml(cmd_args.xmlFile)


if __name__ == '__main__':

    # developer use
    #sys.argv.append('-h')
    sys.argv.append('config.xml')

    main()


########### SVN repository information ###################
# $Date: 2014-04-01 16:52:56 +0000 (Tue, 01 Apr 2014) $
# $Author: jemian $
# $Revision: 1534 $
# $URL: topdoc/branches/xml_2014-03-31/src/topdoc/TopDoc.py $
# $Id: TopDoc.py 1534 2014-04-01 16:52:56Z jemian $
########### SVN repository information ###################