added a script to automaitcally fix 'Derived from' doc sections; updated the 'Library...

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@48100 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

diff --git a/misc/scripts/update_doc_baseclasses.py b/misc/scripts/update_doc_baseclasses.py
new file mode 100644 (file)
index 0000000..857155d
--- /dev/null
+++ b/misc/scripts/update_doc_baseclasses.py
@@ -0,0 +1,130 @@
+##############################################################################\r
+# Name:       misc/scripts/update_doc_baseclasses.py\r
+# Purpose:    Warns about missing classes in the "Derived from" \r
+#             sections in the doc files\r
+# Created:    2007-07-28\r
+# RCS-ID:     $Id: makeunixtags.sh 46320 2007-06-04 11:02:29Z VZ $\r
+# Copyright:  (c) 2007 Francesco Montorsi\r
+# Licence:    wxWindows licence\r
+##############################################################################\r
+\r
+from update_doc_utils import scanTexFiles\r
+\r
+# classes whose docs cannot be fixed automatically\r
+# because of:\r
+#   1) multiple inheritance\r
+#   2) other strange things specific of these classes\r
+EXCEPTIONS=['wxNotebook','wxChoicebook','wxListbook','wxToolbook','wxTreebook','wxURLDataObject','wxHScrolledWindow','wxVScrolledWindow','wxVarHVScrollHelper','wxHVScrolledWindow','wxFileStream']\r
+\r
+def myCallback(classname, texFileName, content, i):\r
+    # now search the base classes for this class\r
+    baseclasses = []\r
+    for j in range(i,len(content)):\r
+        line = content[j]\r
+        if line.startswith("\wxheading{Derived from}"):\r
+            # take all lines contained between this \wxheading and the next one\r
+            # as base classes\r
+            for k in range(j+1,len(content)):\r
+                line = content[k]\r
+                if "\wxheading" in line:\r
+                    break\r
+                elif "\helpref" in line:\r
+                    baseclasses.append(line)\r
+            break   # we've already processed the 'derived from' section for this class\r
+\r
+    if baseclasses == []:\r
+        print " no base classes declared for class %s" % classname\r
+        return True     # keep going on with next \class tags\r
+\r
+    # polish baseclasses list\r
+    for i in range(len(baseclasses)):\r
+        s = baseclasses[i]\r
+        baseclasses[i] = s[s.find("{")+1:s.find("}")]\r
+\r
+    # store the baseclasses\r
+    tree[classname] = baseclasses\r
+    treetex[classname] = texFileName\r
+    treepos[classname] = j+1\r
+    print " class '%s' has %d base class(es): %s" % (classname, len(baseclasses), ','.join(baseclasses))\r
+\r
+    return True\r
+\r
+\r
+tree = dict()\r
+treetex = dict()\r
+treepos = dict()\r
+count = scanTexFiles(myCallback)\r
+\r
+print "\nProcessed %d files." % count\r
+print "\nNow starting to compare the base class lists.\n"\r
+\r
+def getFullListOfBaseClasses(classname):\r
+    if classname not in tree or classname=='':\r
+        return []\r
+\r
+    # only use the first base class of info taken from .tex files\r
+    # i.e. we assume that at least the first class declared as base class is always correct\r
+    baseclass = tree[classname][0]\r
+    return [baseclass] + getFullListOfBaseClasses(baseclass)\r
+\r
+# now compare the theorical list of base classes with the list of base\r
+# classes taken from the .tex files\r
+fixed=0\r
+tofix=set()\r
+for classname in tree:\r
+    theorical=getFullListOfBaseClasses(classname)\r
+    real=tree[classname]\r
+\r
+    # compare them\r
+    if real!=theorical:\r
+        print "* for class '%s' documented in '%s'" % (classname,treetex[classname])\r
+        print "  theorical list: %s" % theorical\r
+        print "  declared list:  %s" % real\r
+\r
+        if classname in EXCEPTIONS:\r
+            tofix.add(treetex[classname])\r
+            print "  cannot fix automatically (blacklisted class!)\n"\r
+            continue\r
+\r
+        # fix it!\r
+        file = open(treetex[classname], "r")\r
+        content = file.readlines()\r
+\r
+        #print "old content is:"\r
+        #print ''.join(content)\r
+\r
+        # remove old \helpref lines\r
+        startidx = treepos[classname]\r
+        count = 0\r
+        while count < len(tree[classname]):\r
+            # we want to remove n \helpref lines, where 'n' is the\r
+            # number of base classes declared\r
+            if content[startidx].startswith('\helpref'):\r
+                del content[startidx]\r
+                count = count+1\r
+            else:\r
+                startidx = startidx+1 # probably an empty line\r
+\r
+        # insert new ones\r
+        if len(theorical)>1:\r
+            for j in range(len(theorical)-1):\r
+                c = theorical[j]\r
+                content.insert(startidx+j, "\helpref{%s}{%s}\\\\\n" % (c, c.lower()))\r
+        else:\r
+            j=-1\r
+        c = theorical[j+1]\r
+        content.insert(startidx+j+1, "\helpref{%s}{%s}\n" % (c, c.lower()))\r
+\r
+        #print "new content is:"\r
+        #print ''.join(content)\r
+\r
+        # save the file\r
+        file = open(treetex[classname], "w")\r
+        file.write(''.join(content))\r
+        file.flush()\r
+\r
+        print "  fixed the .tex file\n"\r
+        fixed=fixed+1\r
+\r
+print "Total number of errors reported: %d" % fixed\r
+print "There are %d files to fix manually:\n%s" % (len(tofix), '\n'.join(tofix))\r

diff --git a/misc/scripts/update_doc_libs.py b/misc/scripts/update_doc_libs.py
old mode 100644 (file)
new mode 100755 (executable)
index 3a57056..fbedee3
--- a/misc/scripts/update_doc_libs.py
+++ b/misc/scripts/update_doc_libs.py
@@ -7,103 +7,94 @@
 # Licence:    wxWindows licence\r
 ##############################################################################\r
 \r
 # Licence:    wxWindows licence\r
 ##############################################################################\r
 \r

-import sys, os, glob, distutils.file_util\r
+from update_doc_utils import scanTexFiles\r

 \r
 \r

-tofix = set()\r
-count = 0\r
-for f in glob.glob('*.tex'):\r
-    file = open(f, "r")\r
-    if not file:\r
-        print "could not open %s" % f\r
-        continue\r
-    print "opened file %s" % f\r
-    count = count + 1\r
-    \r
-    # search \class\r
-    content = file.readlines()\r
-    classdecl = 0\r
-    for i in range(len(content)):\r
-        line = content[i]\r
-        if "\class{" in line:\r
-            classdecl = classdecl + 1\r
-            \r
-            classname = line\r
-            classname = classname[classname.find("\class{"):]\r
-            classname = classname[classname.find("{")+1:classname.find("}")]\r
-            print " the class declared is named '%s'" % classname\r
-            \r
-            tofix.add(f)     # consider this .tex broken\r
-            \r
-            # now search the include file for this class\r
-            include = ""\r
-            for j in range(i,len(content)):\r
-                line = content[j]\r
-                if "wx/" in line and ".h" in line:\r
-                    include = line[line.find("wx/"):line.find(".h")+2]\r
+INCLUDE_PATH="../../include"\r
+\r
+def myCallback(classname, texFileName, content, i):\r
+    tofix.add(texFileName)     # consider this .tex broken\r
+\r
+    # now search the include file for this class\r
+    include = ""\r
+    for j in range(i,len(content)):\r
+        line = content[j]\r
+        if "wx/" in line and ".h" in line:\r
+            include = line[line.find("wx/"):line.find(".h")+2]\r
+            break\r
+    if include == "":\r
+        print " no include file declared for class %s" % classname\r
+        return True # go on with next \class\r
+\r
+    include = include.replace("\\_", "_")\r
+    print " the include file for %s is %s" % (classname, include)\r
+\r
+    # does this .tex already contains the \wxheading{Library} section nearby the include file?\r
+    for k in range(j,min(len(content), j+3)):\r
+        line = content[k]\r
+        if "\wxheading{Library}" in line:\r
+            print " this \class section already has its \wxheading{Library} section... skipping"\r
+            tofix.remove(texFileName) # was a valid .tex (at least for current class)\r
+            return True   # go on with next \class\r
+\r
+    # now try to understand which lib contains this class\r
+    include = INCLUDE_PATH + "/" + include\r
+    header = open(include, "r")\r
+    if not header:\r
+        print " could not open %s" % include\r
+        return True # go on with next \class\r
+\r
+    decl = ""\r
+    content2 = header.readlines()\r
+\r
+    # if they exist append port-specific headers contents\r
+    for c in ["wx/gtk/", "wx/msw/", "wx/mac/", "wx/generic/"]:\r
+        try:\r
+            temp = include.replace("wx/", c)\r
+            print " trying to open %s..." % temp\r
+            header = open(temp, "r")\r
+            headercontents = header.readlines()\r
+            content2 = content2 + headercontents\r
+            print " added %d lines from %s" % (len(headercontents), temp)\r
+        except:\r
+            pass\r
+\r
+    # now search for the export-declaration associated with this class\r
+    for line in content2:\r
+        if "class " in line and classname in line:\r
+            if line.find("class") < line.find(classname):  # could be a comment\r
+                if "_" in line:\r
+                    decl = line[line.find("_")+1:]\r
+                    decl = decl[:decl.find(" ")]\r
+                    decl = decl.replace("FWD_", "")\r
+                    decl = decl[0:1].upper() + decl[1:].lower()\r
+                    break\r
+                elif " WXDLLEXPORT " in line:\r
+                    decl = "Core"\r

                     break\r
                     break\r

-            if include == "":\r
-                print " no include file declared for class %s" % classname\r
-                continue\r
-            \r
-            include = include.replace("\\_", "_")\r
-            print " the include file for %s is %s" % (classname, include)\r
-            \r
-            # now try to understand which libs contains this class\r
-            include = "../../../include/" + include\r
-            header = open(include, "r")\r
-            if not file:\r
-                print " could not open %s" % include\r
-                continue\r
-\r
-            decl = ""\r
-            content2 = header.readlines()\r
-            \r
-            # if they exist append port-specific headers contents\r
-            for c in ["wx/gtk/", "wx/msw/", "wx/mac/", "wx/generic/"]:\r
-                try:\r
-                    temp = include.replace("wx/", c)\r
-                    print " trying to open %s..." % temp\r
-                    header = open(temp, "r")\r
-                    headercontents = header.readlines()\r
-                    content2 = content2 + headercontents\r
-                    print " added %d lines from %s" % (len(headercontents), temp)\r
-                except:\r
-                    pass\r
-            \r
-            for line in content2:\r
-                if "class " in line and classname in line:\r
-                    if line.find("class") < line.find(classname):  # could be a comment\r
-                        if "_" in line:\r
-                            decl = line[line.find("_")+1:]\r
-                            decl = decl[:decl.find(" ")]\r
-                            decl = decl.replace("FWD_", "")\r
-                            decl = decl[0:1].upper() + decl[1:].lower()\r
-                            break\r
-                        elif " WXDLLEXPORT " in line:\r
-                            decl = "Core"\r
-                            break\r
-                        \r
-            if decl == "":\r
-                print " no declaration associated with %s" % classname\r
-                continue\r
-            \r
-            print " the declaration associated with %s is %s" % (classname, decl)\r
-            tofix.remove(f) # was a valid .tex (at least for current class)\r
-            \r
-            # now modify the .tex file\r
-            content.insert(j+2, "\wxheading{Library}\n\n\helpref{wx%s}{librarieslist}\n\n" % decl)\r
-            \r
-            # write it\r
-            file = open(f, "w")\r
-            file.write(''.join(content))\r
-            file.flush()\r
-            \r
-            file = open(f, "r")\r
-\r
-            print " updated %s" % f\r
-\r
-            \r
-    print " file %s contains %d class declarations" % (f, classdecl)\r
-\r
-print "\nProcessed %d files." % count\r
-print "There are %d files to fix:\n%s" % (len(tofix), '\n'.join(tofix))\r
+\r
+    if decl == "":\r
+        print " no declaration associated with %s" % classname\r
+        return True # go on with next \class\r
+\r
+    print " the declaration associated with %s is %s" % (classname, decl)\r
+    tofix.remove(texFileName) # was a valid .tex (at least for current class)\r
+\r
+    # now modify the .tex file\r
+    content.insert(j+2, "\wxheading{Library}\n\n\helpref{wx%s}{librarieslist}\n\n" % decl)\r
+\r
+    # write it\r
+    file = open(texFileName, "w")\r
+    file.write(''.join(content))\r
+    file.flush()\r
+\r
+    print " updated %s" % texFileName\r
+    fixed = fixed+1\r
+\r
+    return True\r
+\r
+fixed = 0\r
+tofix = set()\r
+count = scanTexFiles(myCallback)\r
+\r
+print "\nProcessed %d files, automatically fixed %d files." % (count, fixed)\r
+print "There are %d files to fix manually:\n%s" % (len(tofix), '\n'.join(tofix))\r

diff --git a/misc/scripts/update_doc_utils.py b/misc/scripts/update_doc_utils.py
new file mode 100755 (executable)
index 0000000..7b8382e
--- /dev/null
+++ b/misc/scripts/update_doc_utils.py
@@ -0,0 +1,49 @@
+##############################################################################\r
+# Name:       misc/scripts/update_doc_utils.py\r
+# Purpose:    base utilities for others update_doc_*.py scripts\r
+# Created:    2007-08-1\r
+# RCS-ID:     $Id: makeunixtags.sh 46320 2007-06-04 11:02:29Z VZ $\r
+# Copyright:  (c) 2007 Francesco Montorsi\r
+# Licence:    wxWindows licence\r
+##############################################################################\r
+\r
+import sys, os, glob, distutils.file_util\r
+\r
+DOCS_PATH="../../docs/latex/wx"\r
+\r
+# Calls the given callback with the name of a documented class, its .tex related file,\r
+# the content of that .tex file and the number of the line of the relative \class tag,\r
+# for all documented class in DOCS_PATH. If the callback returns false the processing is stopped.\r
+# Returns the number of .tex files processed.\r
+def scanTexFiles(callback):\r
+    count = 0\r
+    for f in glob.glob(DOCS_PATH + '/*.tex'):\r
+        file = open(f, "r")\r
+        if not file:\r
+            print "could not open %s" % f\r
+            continue\r
+        print "opened file %s" % f\r
+        count = count + 1\r
+\r
+        # search \class tags\r
+        content = file.readlines()\r
+        classdecl = 0\r
+        for i in range(len(content)):\r
+            line = content[i]\r
+            if "\class{" in line:\r
+                classdecl = classdecl + 1\r
+\r
+                # polish the class name\r
+                classname = line\r
+                classname = classname[classname.find("\class{"):]\r
+                classname = classname[classname.find("{")+1:classname.find("}")]\r
+                print " the class declared is named '%s'" % classname\r
+\r
+                # process this \class\r
+                if not callback(classname, f, content, i):\r
+                    return count\r
+\r
+        print " file %s contains %d class declarations" % (f, classdecl)\r
+\r
+    return count\r
+\r