Put the module docstrings on the module index pages

Plus some other changes to start using using the "wx." prefix on names in the docs. (More are still needed but this is a start.

b

@@ -5,11 +5,11 @@
 if [ "$OSTYPE" = "cygwin" ]; then
     PYTHON=`which python.exe`
     echo $PYTHON
-    $PYTHON -u build.py "$@"
+    $PYTHON -u build.py --dev "$@"
 else
     PYTHON=`which python`
     echo $PYTHON
-    $PYTHON -u build.py "$@"
+    $PYTHON -u build.py --dev "$@"
 fi
 
 exit $?

etg/_core.py

@@ -16,7 +16,7 @@
 NAME      = "_core"   # Base name of the file to generate to for this script
 DOCSTRING = """\
 The classes in this module are the most commonly used classes for wxPython,
-which is why they have been made visible in the core ``wx`` namespace.
+which is why they have been made visible in the core `wx` namespace.
 Everything you need for building typical GUI applications is here.
 """
 

etgtools/sip_generator.py

@@ -87,7 +87,7 @@ def generateModule(self, module, stream):
             if module.name.startswith('_'):
                 doc = ''
                 if module.docstring:
-                    doc = '\n"""\n%s\n"""\n' % module.docstring 
+                    doc = '\n"""\n%s"""\n' % module.docstring
                 stream.write("""\
 %%Extract(id=pycode%s, order=5)
 # This file is generated by wxPython's SIP generator.  Do not edit by hand.

sphinxtools/constants.py

@@ -86,6 +86,33 @@
                       }
 
 NO_MODULE = {
+            # -- core -- #
+            'AlphaPixelData'            : 'wx.',
+            'AlphaPixelData_Accessor'   : 'wx.',
+            'ButtonLabel'               : 'wx.',
+            'CallLater'                 : 'wx.',
+            'ChildrenRepositioningGuard': 'wx.',
+            'GenericDragImage'          : 'wx.',
+            'GenericMessageDialog'      : 'wx.',
+            'HSVValue'                  : 'wx.',
+            'MessageParameters'         : 'wx.',
+            'NativePixelData'           : 'wx.',
+            'NativePixelData_Accessor'  : 'wx.',
+            'PixelDataBase'             : 'wx.',
+            'PyApp'                     : 'wx.',
+            'PyCommandEvent'            : 'wx.',
+            'PyEvent'                   : 'wx.',
+            'PyEventBinder'             : 'wx.',
+            'PyOnDemandOutputWindow'    : 'wx.',
+            'PySimpleApp'               : 'wx.',
+            'PySingleChoiceDialog'      : 'wx.',
+            'RGBValue'                  : 'wx.',
+            'ScrolledCanvas'            : 'wx.',
+            'ScrolledWindow'            : 'wx.',
+            'TimeZone'                  : 'wx.',
+            'Tm'                        : 'wx.',
+            'WindowBase'                : 'wx.',
+
              # -- wxAdvanced -- #
              # Widgets
              'DatePickerCtrlGeneric': 'wx.adv.',
@@ -150,6 +177,9 @@
 
              # Enums/constants
              'XmlResourceFlags'        : 'wx.xrc.',
+
+             # -- wx.msw -- #
+             'PyAxBaseWindow'          : 'wx.msw',
              }
 
 # Other C++ specific things to strip away

sphinxtools/postprocess.py

@@ -15,12 +15,6 @@
 import re
 import glob
 import random
-import subprocess
-
-if sys.version_info < (3,):
-    import cPickle as pickle
-else:
-    import pickle
 
 # Phoenix-specific imports
 from buildtools.config import copyIfNewer, writeIfChanged, newer, getVcsRev, textfile_open
@@ -29,6 +23,9 @@
 from .utilities import Wx2Sphinx, PickleFile
 from .constants import HTML_REPLACE, TODAY, SPHINXROOT, SECTIONS_EXCLUDE
 from .constants import CONSTANT_INSTANCES, WIDGETS_IMAGES_ROOT, SPHINX_IMAGES_ROOT
+from .constants import DOCSTRING_KEY
+
+# ----------------------------------------------------------------------- #
 
 
 def MakeHeadings():
@@ -367,11 +364,11 @@ def ReformatFunctions(file):
     pf = PickleFile(file)
     functions = pf.read()
 
-    if local_file.count('.') == 1:
+    if local_file.count('.') == 2:
         # Core functions
-        label = 'Core'
+        label = 'wx Core'
     else:
-        label = local_file.split('.')[0:-2][0]
+        label = '.'.join(local_file.split('.')[0:2])
 
     names = list(functions.keys())
     names = [name.lower() for name in names]
@@ -420,36 +417,46 @@ def MakeClassIndex(sphinxDir, file):
 
     pf = PickleFile(file)
     classes = pf.read()
+    module_docstring = classes.get(DOCSTRING_KEY)
+    if module_docstring is not None:
+        del classes[DOCSTRING_KEY]
+
+    if local_file.startswith('wx.1'):
         # Core functions
-        label = 'Core'
-        module = ''
-        enumDots = 1
+        label = 'wx Core'
+        module = 'wx'
+        enumDots = 2
+        # Take care to get only files starting with "wx.UpperName", not
+        # "wx.lower.UpperName". This is so we don't put all the enums in the
+        # submodules in the core wx module too.
+        # TODO: This may not work on case-insensitive file systems, check it.
+        enum_files = glob.glob(sphinxDir + '/wx.[A-Z]*.enumeration.txt')
     else:
-        label = local_file.split('.')[0:-2][0]
+        label = '.'.join(local_file.split('.')[0:2])
         module = label
-        enumDots = 2
+        enumDots = 3
+        enum_files = glob.glob(sphinxDir + '/%s*.enumeration.txt' % module)
 
-    enum_files = glob.glob(sphinxDir + '/%s*.enumeration.txt'%module)
     enum_base = [os.path.split(os.path.splitext(enum)[0])[1] for enum in enum_files]
 
     names = list(classes.keys())
     names.sort()
 
     text = ''
     if module:
-        text += '\n\n.. module:: %s\n\n'%module
+        text += '\n\n.. module:: %s\n\n' % module
 
-    text += templates.TEMPLATE_CLASS_INDEX % (label, label)
+    text += templates.TEMPLATE_CLASS_INDEX % (label, module_docstring)
 
     text += 80*'=' + ' ' + 80*'=' + '\n'
-    text += '%-80s **Short Description**\n'%'**Class**'
+    text += '%-80s **Short Description**\n' % '**Class**'
     text += 80*'=' + ' ' + 80*'=' + '\n'
 
     for cls in names:
         out = classes[cls]
         if '=====' in out:
             out = ''
-        text += '%-80s %s\n'%(':ref:`%s`'%Wx2Sphinx(cls)[1], out)
+        text += '%-80s %s\n' % (':ref:`%s`' % Wx2Sphinx(cls)[1], out)
 
     text += 80*'=' + ' ' + 80*'=' + '\n\n'
 

sphinxtools/templates.py

@@ -171,15 +171,11 @@
 **%s** Classes
 =========================================================================
 
-This is an alphabetical listing of all the classes defined in the **%s** module, together with a brief description of them (if available).
-
-You can look up a class using the alphabetical listing of them.
-
+%s
 
 Class Summary
 =============
 
-
 '''
 
 

sphinxtools/utilities.py

@@ -693,6 +693,11 @@ def PickleClassInfo(class_name, element, short_description):
 
 # ----------------------------------------------------------------------- #
 
+# TODO: It would be nice to handle tracking the modules in a better way that
+# doesn't need to import and use the ITEMS list in etg files.  There are too
+# many items added on the fly to try and keep track of them separately.  We
+# can add the module name to the saved data while in the etg/generator stage.
+
 global ALL_ITEMS
 ALL_ITEMS = {}