Phoenix: new updates to better handle wx.lib documentation.

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

docs/sphinx/_templates/main.html

@@ -74,20 +74,26 @@
 
   <h2>Documentation</h2>
 
-  <table class="contentstable" align="center" style="margin-left: 30px"><tr>
+  <table class="contentstable" align="center" style="margin-left: 30px">
+  	<tr>
     <td width="50%">
       <p class="biglink"><a class="biglink" href="{{ pathto("1classindex") }}">Phoenix Widgets</a><br/>
          <span class="linkdescr">Swig-ed from wxWidgets</span></p>
+         	
+         	<br/>
       <p class="biglink"><a class="biglink" href="{{ pathto("functions") }}">Phoenix Functions</a><br/>
          <span class="linkdescr">Standalone/Static functions</span></p>
-    </td><td width="50%">
+    </td>
+    <td width="50%">
       <p class="biglink"><a class="biglink" >Wrapped Sub-Modules</a><br/>
          <span class="linkdescr">Contained in <i>wx.something</i> modules</span></p>
-	<p>
-	</p>
+	  <p>
+	  </p>
 	<ul>
       <li><a href="dataview.1classindex.html">dataview</a></li>
      </ul>
+      <p class="biglink"><a class="biglink" href="{{ pathto("lib") }}">wx.lib</a><br/>
+         <span class="linkdescr">Our pure-Python library of widgets</span></p>
     </td></tr>
   </table>
 

docs/sphinx/rest_substitutions/snippets/python/converted/MDIParentFrame.OnCreateClient.1.py

@@ -0,0 +1,3 @@
+    
+            frame = MyParentFrame()
+            frame.Create(parent, myParentFrameId, "My Parent Frame")

sphinxtools/librarydescription.py

@@ -9,7 +9,8 @@ from subprocess import Popen, PIPE
 
 from inspect import getmro, getclasstree, getdoc, getcomments
 
-from utilities import MakeSummary, ChopDescription, WriteSphinxOutput, PickleClassInfo
+from utilities import MakeSummary, ChopDescription, WriteSphinxOutput
+from utilities import FindControlImages, PickleClassInfo
 from constants import object_types, MODULE_TO_ICON
 import templates
 
@@ -72,7 +73,7 @@ def generic_summary(libraryItem, stream):
         table = []
         for item in sub_list:
             
-            if item.is_redundant:
+            if item.is_redundant or item.GetShortName().startswith('__test'):
                 continue
             
             docs = ChopDescription(ReplaceWxDot(item.docs))
@@ -102,7 +103,9 @@ def ReplaceWxDot(text):
     
     # Signle ticks with 'wx.' in them... try and referencing them
     text = re.sub(r'`wx\.(.*?)`', r'`\1`   ', text)
-    
+
+    # Masked is funny...
+    text = text.replace('</LI>', '')
     return text
 
     
@@ -282,7 +285,7 @@ class Library(ParentBase):
         print '\n\nReST-ifying %s...\n\n'%self.base_name
         stream = StringIO()
 
-        header = templates.TEMPLATE_DESCRIPTION%(self.base_name, self.base_name + ' Library')
+        header = templates.TEMPLATE_DESCRIPTION%(self.base_name, self.base_name)
         stream.write(header)
 
         stream.write(ReplaceWxDot(self.docs) + '\n\n')
@@ -316,6 +319,9 @@ class Module(ParentBase):
 
 
     def ToRest(self):
+
+        if self.is_redundant or self.GetShortName().startswith('__test'):
+            return
         
         stream = StringIO()
 
@@ -325,8 +331,9 @@ class Module(ParentBase):
 
         stream.write('.. module:: %s\n\n'%self.name)
         stream.write('.. currentmodule:: %s\n\n'%self.name)
+        stream.write('.. highlight:: python\n\n')
             
-        header = templates.TEMPLATE_DESCRIPTION%(self.name, '%s %s'%(self.name, label))
+        header = templates.TEMPLATE_DESCRIPTION%(self.name, '%s'%self.GetShortName())
         
         stream.write(header)
         stream.write(ReplaceWxDot(self.docs) + '\n\n')
@@ -345,22 +352,21 @@ class Module(ParentBase):
 
         generic_summary(self, stream)
 
-        if self.kind != object_types.PACKAGE:
-            functions = self.GetItemByKind(object_types.FUNCTION)
+        functions = self.GetItemByKind(object_types.FUNCTION)
 
-            count = 0
-            for fun in functions:
-                if not fun.is_redundant:
-                    count = 1
-                    break
+        count = 0
+        for fun in functions:
+            if not fun.is_redundant:
+                count = 1
+                break
 
-            if count > 0:
-                stream.write('\n\nFunctions\n===========\n\n')
-                
-            for fun in functions:
-                if fun.is_redundant:
-                    continue
-                fun.Write(stream)
+        if count > 0:
+            stream.write('\n\nFunctions\n------------\n\n')
+            
+        for fun in functions:
+            if fun.is_redundant:
+                continue
+            fun.Write(stream)
 
         WriteSphinxOutput(stream, self.sphinx_file)
 
@@ -394,7 +400,7 @@ class Class(ParentBase):
                 name_parts = sup.split('.')
                 sup = name_parts[-1]
 
-            sortedSupClasses.append(sup)
+            sortedSupClasses.append(sup.replace('wx.', ''))
 
         sortedSupClasses.sort()    
            
@@ -412,10 +418,16 @@ class Class(ParentBase):
                 name_parts = cls.split('.')
                 cls = name_parts[-1]
 
-            sortedSubClasses.append(cls)
+            sortedSubClasses.append(cls.replace('wx.', ''))
 
         sortedSubClasses.sort()
+
+        if len(sortedSubClasses) == 1 and sortedSubClasses[0] == 'object':
+            sortedSubClasses = []
         
+        if len(sortedSupClasses) == 1 and sortedSupClasses[0] == 'object':
+            sortedSupClasses = []
+
         self.class_tree = make_class_tree(getclasstree(getmro(obj)))
         
         self.subClasses = sortedSubClasses
@@ -431,7 +443,7 @@ class Class(ParentBase):
 
     def ToRest(self):
 
-        if self.is_redundant:
+        if self.is_redundant or self.GetShortName().startswith('__test'):
             return
 
         stream = StringIO()
@@ -440,10 +452,13 @@ class Class(ParentBase):
         current_module = '.'.join(parts[0:-1])
 
         stream.write('.. currentmodule:: %s\n\n'%current_module)
+        stream.write('.. highlight:: python\n\n')
+
+        class_docs = ReplaceWxDot(self.docs)
         
         header = templates.TEMPLATE_DESCRIPTION%(self.name, self.GetShortName())
         stream.write(header)
-        stream.write(ReplaceWxDot(self.docs) + '\n\n')
+        stream.write(class_docs + '\n\n')
 
         if self.inheritance_diagram:
             png, map = self.inheritance_diagram.MakeInheritanceDiagram()
@@ -451,22 +466,33 @@ class Class(ParentBase):
             image_desc = templates.TEMPLATE_INHERITANCE % (short_name, png, short_name, map)
             stream.write(image_desc)
 
+        appearance = FindControlImages(self.name.lower())
+        if appearance:
+            appearance_desc = templates.TEMPLATE_APPEARANCE % tuple(appearance)
+            stream.write(appearance_desc + '\n\n')
+
         if self.subClasses:
-            subs = [':ref:`%s`'%cls for cls in self.superClasses]
+            subs = [':ref:`%s`'%cls for cls in self.subClasses]
             subs = ', '.join(subs)
             subs_desc = templates.TEMPLATE_SUBCLASSES % subs
             stream.write(subs_desc)
 
         if self.superClasses:
-            subs = [':ref:`%s`'%cls for cls in self.superClasses]
-            subs = ', '.join(subs)
-            subs_desc = templates.TEMPLATE_SUPERCLASSES % subs
-            stream.write(subs_desc)
+            sups = [':ref:`%s`'%cls for cls in self.superClasses]
+            sups = ', '.join(sups)
+            sups_desc = templates.TEMPLATE_SUPERCLASSES % sups
+            stream.write(sups_desc)
 
         generic_summary(self, stream)
 
         stream.write(templates.TEMPLATE_API)
-        stream.write("\n.. class:: %s\n\n\n"%self.signature)
+        stream.write("\n.. class:: %s\n\n"%self.signature)
+
+        docs = ''
+        for line in class_docs.splitlines(True):
+            docs += ' '*3 + line
+            
+        stream.write(docs + '\n\n')
 
         methods = self.GetItemByKind(object_types.METHOD, object_types.INSTANCE_METHOD)
         properties = self.GetItemByKind(object_types.PROPERTY)
@@ -607,6 +633,15 @@ class Method(ChildrenBase):
         if self.signature.startswith('def '):
             self.signature = self.signature[4:]
 
+        if '@staticmethod' in self.signature:
+            self.kind = object_types.STATIC_METHOD
+        elif '@classmethod' in self.signature:
+            self.kind = object_types.CLASS_METHOD
+
+        if ' def ' in self.signature:
+            index = self.signature.index(' def ')
+            self.signature = self.signature[index+5:].strip()
+            
         if not self.signature.strip():
             self.is_redundant = True            
 
@@ -620,7 +655,12 @@ class Method(ChildrenBase):
             stream.write('.. function:: %s\n\n'%self.signature)
             indent = 3*' '
         else:
-            stream.write('   .. method:: %s\n\n'%self.signature)
+            if self.kind == object_types.STATIC_METHOD:
+                stream.write('   .. staticmethod:: %s\n\n'%self.signature)
+            elif self.kind == object_types.CLASS_METHOD:
+                stream.write('   .. classmethod:: %s\n\n'%self.signature)
+            else:
+                stream.write('   .. method:: %s\n\n'%self.signature)
             indent = 6*' '
 
         if not self.docs.strip():

sphinxtools/modulehunter.py

@@ -46,6 +46,8 @@ except ImportError:
     
 import wx
 
+print '\nUSING VERSION: %s\n'%wx.VERSION_STRING
+
 
 if hasattr(os.path, "relpath"):
     relpath = os.path.relpath # since Python 2.6
@@ -367,6 +369,9 @@ def describe_class(obj, module_class, module_name, constants):
         
     if source_code:
         description = get_constructor(source_code)
+        if '(' not in description and ':' in description:
+            description = description[0:description.index(':')]
+            
         klass.signature = description.strip()
         klass.number_lines = '%d'%len(source_code.split("\n"))
 

sphinxtools/postprocess.py

@@ -630,12 +630,12 @@ def PostProcess(folder):
 
             if index < len_split - 1:
 
-                if line.strip() == '<br><hr />':
-                    
+                if line.strip() == '<br><hr />' or line.strip() == '<dd><br><hr />':                    
                     next_line = splitted_text[index+1]
                     stripline = next_line.strip()
                     
-                    if (stripline == '<dl class="staticmethod">' or stripline == '<dl class="method">') and not methods_done:
+                    if (stripline == '<dl class="staticmethod">' or stripline == '<dl class="method">' \
+                       or stripline == '<dl class="classmethod">') and not methods_done:
                         line = '<br><h3>Methods<a class="headerlink" href="#methods" title="Permalink to this headline">¶</a></h3>' + '\n' + line
                         methods_done = True
                         

sphinxtools/utilities.py

@@ -387,9 +387,10 @@ def FindDescendants(element, tag, descendants=None):
 
 # ----------------------------------------------------------------------- #
 
-def FindControlImages(element):
+def FindControlImages(elementOrString):
     """
-    Given the input `element` (an instance of `xml.etree.ElementTree.Element`)
+    Given the input `element` (an instance of `xml.etree.ElementTree.Element`
+    or a plain string)
     representing a Phoenix class description, this function will scan the
     doxygen image folder ``DOXYROOT`` to look for a widget screenshot.
 
@@ -398,7 +399,8 @@ def FindControlImages(element):
     in one of its sub-folders (``wxmsw``, ``wxgtk``, ``wxmac``) depending on
     which platform the screenshot was taken.
 
-    :param xml.etree.ElementTree.Element `element`: the XML element we want to examine.
+    :param `elementOrString`: the XML element we want to examine (an instance of
+     xml.etree.ElementTree.Element) or a plain string (usually for wx.lib).
 
     :rtype: `list`
 
@@ -411,11 +413,15 @@ def FindControlImages(element):
 
     """       
 
-    class_name = RemoveWxPrefix(element.name) or element.pyName
-    py_class_name = Wx2Sphinx(class_name)[1]
+    if isinstance(elementOrString, basestring):
+        class_name = py_class_name = elementOrString.lower()
+    else:
+        element = elementOrString
+        class_name = RemoveWxPrefix(element.name) or element.pyName
+        py_class_name = Wx2Sphinx(class_name)[1]
 
-    class_name = class_name.lower()
-    py_class_name = py_class_name.lower()
+        class_name = class_name.lower()
+        py_class_name = py_class_name.lower()
 
     image_folder = os.path.join(DOXYROOT, 'images')