misc/scripts/update_doc_baseclasses.py

   1 ##############################################################################
   2 # Name:       misc/scripts/update_doc_baseclasses.py
   3 # Purpose:    Warns about missing classes in the "Derived from"
   4 #             sections in the doc files
   5 # Created:    2007-07-28
   6 # RCS-ID:     $Id$
   7 # Copyright:  (c) 2007 Francesco Montorsi
   8 # Licence:    wxWindows licence
   9 ##############################################################################
  10
  11 from update_doc_utils import scanTexFiles
  12
  13 # classes whose docs cannot be fixed automatically
  14 # because of:
  15 #   1) multiple inheritance
  16 #   2) other strange things specific of these classes
  17 EXCEPTIONS=['wxNotebook','wxChoicebook','wxListbook','wxToolbook','wxTreebook','wxURLDataObject','wxHScrolledWindow','wxVScrolledWindow','wxVarHVScrollHelper','wxHVScrolledWindow','wxFileStream']
  18
  19 def myCallback(classname, texFileName, content, i):
  20     # now search the base classes for this class
  21     baseclasses = []
  22     for j in range(i,len(content)):
  23         line = content[j]
  24         if line.startswith("\wxheading{Derived from}"):
  25             # take all lines contained between this \wxheading and the next one
  26             # as base classes
  27             for k in range(j+1,len(content)):
  28                 line = content[k]
  29                 if "\wxheading" in line:
  30                     break
  31                 elif "\helpref" in line:
  32                     baseclasses.append(line)
  33             break   # we've already processed the 'derived from' section for this class
  34
  35     if baseclasses == []:
  36         print " no base classes declared for class %s" % classname
  37         return True     # keep going on with next \class tags
  38
  39     # polish baseclasses list
  40     for i in range(len(baseclasses)):
  41         s = baseclasses[i]
  42         baseclasses[i] = s[s.find("{")+1:s.find("}")]
  43
  44     # store the baseclasses
  45     tree[classname] = baseclasses
  46     treetex[classname] = texFileName
  47     treepos[classname] = j+1
  48     print " class '%s' has %d base class(es): %s" % (classname, len(baseclasses), ','.join(baseclasses))
  49
  50     return True
  51
  52
  53 tree = dict()
  54 treetex = dict()
  55 treepos = dict()
  56 count = scanTexFiles(myCallback)
  57
  58 print "\nProcessed %d files." % count
  59 print "\nNow starting to compare the base class lists.\n"
  60
  61 def getFullListOfBaseClasses(classname):
  62     if classname not in tree or classname=='':
  63         return []
  64
  65     # only use the first base class of info taken from .tex files
  66     # i.e. we assume that at least the first class declared as base class is always correct
  67     baseclass = tree[classname][0]
  68     return [baseclass] + getFullListOfBaseClasses(baseclass)
  69
  70 # now compare the theorical list of base classes with the list of base
  71 # classes taken from the .tex files
  72 fixed=0
  73 tofix=set()
  74 for classname in tree:
  75     theorical=getFullListOfBaseClasses(classname)
  76     real=tree[classname]
  77
  78     # compare them
  79     if real!=theorical:
  80         print "* for class '%s' documented in '%s'" % (classname,treetex[classname])
  81         print "  theorical list: %s" % theorical
  82         print "  declared list:  %s" % real
  83
  84         if classname in EXCEPTIONS:
  85             tofix.add(treetex[classname])
  86             print "  cannot fix automatically (blacklisted class!)\n"
  87             continue
  88
  89         # fix it!
  90         file = open(treetex[classname], "r")
  91         content = file.readlines()
  92
  93         #print "old content is:"
  94         #print ''.join(content)
  95
  96         # remove old \helpref lines
  97         startidx = treepos[classname]
  98         count = 0
  99         while count < len(tree[classname]):
 100             # we want to remove n \helpref lines, where 'n' is the
 101             # number of base classes declared
 102             if content[startidx].startswith('\helpref'):
 103                 del content[startidx]
 104                 count = count+1
 105             else:
 106                 startidx = startidx+1 # probably an empty line
 107
 108         # insert new ones
 109         if len(theorical)>1:
 110             for j in range(len(theorical)-1):
 111                 c = theorical[j]
 112                 content.insert(startidx+j, "\helpref{%s}{%s}\\\\\n" % (c, c.lower()))
 113         else:
 114             j=-1
 115         c = theorical[j+1]
 116         content.insert(startidx+j+1, "\helpref{%s}{%s}\n" % (c, c.lower()))
 117
 118         #print "new content is:"
 119         #print ''.join(content)
 120
 121         # save the file
 122         file = open(treetex[classname], "w")
 123         file.write(''.join(content))
 124         file.flush()
 125
 126         print "  fixed the .tex file\n"
 127         fixed=fixed+1
 128
 129 print "Total number of errors reported: %d" % fixed
 130 print "There are %d files to fix manually:\n%s" % (len(tofix), '\n'.join(tofix))