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