Phoenix stuff:

1) Fixes on the problems reported by Werner on wx.EvtHandler (and there were many others, hopefully they should be OK now);
2) Integration of Chris' samples on wx.GridBagSizer (see http://xoomer.virgilio.it/infinity77/Phoenix/GridBagSizer.html#gridbagsizer);
3) Start on the Documentation guidelines (see http://xoomer.virgilio.it/infinity77/Phoenix/DocstringsGuidelines.html);
4) Integration of Werner's patches on _core.py and app.py for the docstrings.


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

docs/sphinx/_templates/main.html

@@ -49,6 +49,17 @@
       shows the main thoughts behind the project Phoenix implementation</li>
   </ul>
 
+<br>
+
+<div class="admonition note">
+ <p class="first admonition-title">Note</p>
+
+    If you wish to help in the documentation effort, the main docstrings guidelines are outlined in 
+    <a href="DocstringsGuidelines.html">this document</a>.
+</div>
+
+<br>
+
   <p>
     The Phoenix documentation has been built automatically starting from XML files representing the
     <a href="http://www.wxwidgets.org/">wxWidgets</a> C++ documentation (generated using <a href="www.doxygen.org/">Doxygen</a>).

docs/sphinx/conf.py

@@ -56,7 +56,7 @@ copyright = u'2012, Andrea Gavana'
 # The short X.Y version.
 version = '2.9'
 # The full version, including alpha/beta/rc tags.
-release = '2.9.3.74 (Phoenix)'
+release = '2.9.4.80 (Phoenix)'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -158,7 +158,7 @@ html_use_index = True
 html_split_index = True
 
 # If true, links to the reST sources are added to the pages.
-html_show_sourcelink = False
+html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #html_show_sphinx = True

docs/sphinx/rest_substitutions/overviews/DocstringsGuidelines.rst

@@ -0,0 +1,271 @@
+.. include:: headings.inc
+
+.. highlight:: rst
+
+
+.. _docstrings guidelines:
+
+==================================================
+|phoenix_title|  **Phoenix Docstrings Guidelines**
+==================================================
+
+This document gives a brief introduction about the current docstrings standards
+in the Phoenix project. Most of the documentation in the Phoenix core is automatically
+generated by parsing the wxWidgets XML docs; however, Phoenix has its own pure-Python
+functions and classes in at least two places:
+
+* **Core Library**: examples include :ref:`CallLater` and :func:`date2pydate`, which require
+  manual input od the documentation strings. This is achieved by editing the source Python files
+  located in the ``etg`` folder in the Phoenix directory tree;
+* **wx.lib**: the whole of ``wx.lib`` (and its sub-folders) is made up of pure-Python modules,
+  ofter representing owner-drawn widgets which are not available as wrapped modules. Again,
+  this requires manual editing of the source Python files.
+
+This document is a starting point in setting some reasonable standards on how the pure-Python
+docstrings may be edited and improved to make the overall appearance of the Phoenix documentation
+consistent and pleasant.
+
+
+.. _info field lists:
+
+Info Field Lists
+----------------
+
+`Info Field Lists` refer to the various options available while documenting a method or a function,
+and in particular its parameters, keywords, return type and possibly raised Python `Exceptions`.
+
+Inside Python object description directives, reST field lists with these fields
+are recognized and formatted nicely:
+
+* ``param``, ``parameter``, ``arg``, ``argument``, ``key``, ``keyword``:
+  Description of a parameter.
+* ``type``: Type of a parameter.
+* ``raises``, ``raise``, ``except``, ``exception``: That (and when) a specific
+  exception is raised.
+* ``var``, ``ivar``, ``cvar``: Description of a variable.
+* ``returns``, ``return``: Description of the return value.
+* ``rtype``: Return type.
+
+
+The field names must consist of one of these keywords and an argument (except
+for ``returns`` and ``rtype``, which do not need an argument). This is best
+explained by an example::
+
+    .. method:: Set3StateValue(self, state):
+
+       Sets the checkbox item to the given `state`.
+
+       :param `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is off), ``wx.CHK_CHECKED``
+        (check is on) or ``wx.CHK_UNDETERMINED`` (check is mixed).
+       :type `state`: integer
+
+       :returns: ``True`` if the value was successfully set, ``False`` otherwise.
+       :rtype: bool
+
+       :raise: `Exception` when the item is not a 3-state checkbox item.
+
+|
+
+This will render like this:
+
+    .. method:: Set3StateValue(self, state):
+       :noindex:
+
+       Sets the checkbox item to the given `state`.
+
+       :param `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is off), ``wx.CHK_CHECKED``
+        (check is on) or ``wx.CHK_UNDETERMINED`` (check is mixed).
+       :type `state`: integer
+
+       :returns: ``True`` if the value was successfully set, ``False`` otherwise.
+       :rtype: bool
+
+       :raise: `Exception` when the item is not a 3-state checkbox item.
+
+
+|
+
+It is also possible to combine parameter type and description, if the type is a
+single word, like this::
+
+   :param integer `state`: can be one of: ``wx.CHK_UNCHECKED`` (check is off), ``wx.CHK_CHECKED``
+    (check is on) or ``wx.CHK_UNDETERMINED`` (check is mixed).
+
+
+In general, the standards for the ``:param`` field are the following:
+
+1. Do not use the ``@param`` construct, as I am not sure Sphinx and docutils understand it;
+2. Always try and define the parameter type: if the parameter is another Phoenix class, you can simply
+   write this::
+
+       :param Point `pt`: the mouse pointer location.
+
+   Or, alternatively::
+
+       :param `pt`: the mouse pointer location.
+       :type `pt`: `Point`
+
+
+Similarly, for the ``:return:`` and ``:rtype:`` field, you may consider doing the following:
+
+1. Try and put double-backticks on words like ``True``, ``False``, ``None`` and the various
+   Phoenix constants (i.e., ``wx.TR_DEFAULT_STYLE``);
+2. If you can't guess what a method function returns, just leave the ``:returns:`` and ``:rtype:``
+   fields blank.
+
+
+.. seealso:: `Sphinx Info Field List <http://sphinx.pocoo.org/domains.html#info-field-lists>`_
+
+
+.. _admonitions:
+
+Admonitions
+-----------
+
+Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can.
+They contain arbitrary body elements. Typically, an admonition is rendered as an offset block
+in a document, sometimes outlined or shaded, with a title matching the admonition type. For example::
+
+    .. warning:: I am a warning.
+
+
+Will render as:
+
+.. warning:: I am a warning.
+
+|
+
+Currently, the `sphinx_generator` tool recognizes the following admonitions:
+
+1. ``.. note::`` : simple annotations to make a particular comment/sentence
+   stand out against the rest of the documentation strings for a particular class, method or function;
+2. ``.. warning::`` : this admonition normally indicates a problem or a severe limitation of a method,
+   class or function. In the Phoenix world, this may also indicate that a particular widget is not
+   supported under one or more platforms;
+3. ``.. deprecated::`` : used to mark deprecated methods, classes or functions;
+4. ``.. availability::`` : normally employed to make the user understand on which platform(s) a particular
+   functionality is supported/available;
+5. ``.. seealso::`` : added primarily to facilitate the browsing of the docs, this admonition
+   should be employed every time you think a user may be interested in seeing a related/similar method
+   or a function providing an alternative implementation;
+6. ``.. todo::`` : used to mark incomplete methods/functions, or simply as a remainder for the user and
+   the developer that some more functionality needs to be added.
+
+You can put pretty much anything inside an admonition section, as long as it is properly indented. The
+recommendation is to implement it like this::
+
+    .. note::
+
+       The class :ref:`TreeCtrl` can be used to display a tree, with these notes:
+
+       - The note contains all indented body elements
+         following.
+       - It includes this bullet list.
+       
+
+|
+
+Which will render as follows:
+
+.. note::
+
+   The class :ref:`TreeCtrl` can be used to display a tree, with these notes:
+
+   - The note contains all indented body elements
+     following.
+   - It includes this bullet list.
+
+
+
+In addition to the aforementioned admonitions, you can also use the default Sphinx directives
+like ``.. versionadded::`` and ``.. versionchanged::``, to highlight the fact that some method, 
+function or class has been added/modified starting with a particular Phoenix version.
+
+
+.. seealso:: `Sphinx Paragraph-level markup <http://sphinx.pocoo.org/markup/para.html>`_
+
+
+.. _contributing samples:
+
+Contributing Samples
+--------------------
+
+.. highlight:: python
+
+If you wish to contribute a (short) sample to be included in the documentation, please follow 
+these conventions:
+
+1. Name the snippet of code like ``classname.methodname.INTEGER.py``, i.e. if you wish to contribute 2
+   snippets about the :meth:`CheckBox.SetValue` method, please name your snippet files like this:
+
+   * `CheckBox.SetValue.1.py`
+   * `CheckBox.SetValue.2.py`
+   
+   
+2. At the very top of the snippet file (on the first line), put your name, or your alias, or anything
+   you use as internet name preceeded by a double-hash, i.e.:
+   
+   ``##Andrea Gavana``
+   
+   
+   So that your source code looks more or less like this::
+   
+       ##Chris Barker
+       #!/usr/bin/env python
+
+       """
+       A simple test of the GridBagSizer
+       http://wiki.wxpython.org/index.cgi/WriteItYourself
+       """
+   
+       # Whatever code here...
+       def SendSizeEvent(self):
+       
+           self.AdjustMySize()
+
+
+
+.. highlight:: rst
+
+This snippet will end up in the snippets `contrib` folder, to differentiate it from the snippets 
+automatically generated when parsing the wxWidgets C++ XML documentation.
+
+Please keep the snippets as short as possible: they don't need to be fully-runnable and self contained
+applications, they are simply meant to show a particular/clever/unusual way of using a method, a class
+or a function.
+
+Please do send your sample snippets to me at `this <andrea.gavana@gmail.com>`_ e-mail address or, if
+you have commit rights in the current Phoenix SVN area, feel free to upload them yourself under the
+following folder:
+
+``/trunk/docs/sphinx/rest_substitutions/snippets/python/contrib``
+
+
+.. _contributing screenshots:
+
+Contributing Screenshots
+------------------------
+
+Currently Phoenix is relatively short of widgets screenshots, especially on Linux/Mac platforms.
+
+If you wish to contribute a screenshot of a widget to be included in the documentation, please follow 
+these conventions:
+
+- If the widget is a class belonging to the main `wx` namespace, just use the
+  class name in lower case (i.e., `wx.Frame` ==> `frame.png`);
+- If it belongs to a sub-namespace (i.e., `wx.dataview`, `wx.aui`, `wx.html`
+  and so on), it should be named this way (examples):
+
+  1) `wx.dataview.DataViewCtrl` ==> `dataview.dataviewctrl.png`
+  2) `wx.aui.AuiManager` ==> `aui.auimanager.png`
+
+
+Please do send your screenshots to me at `this <andrea.gavana@gmail.com>`_ e-mail address or, if
+you have commit rights in the current Phoenix SVN area, feel free to upload them yourself under the
+following folder:
+
+``/trunk/docs/sphinx/_static/images/widgets/fullsize``
+
+Please make sure to upload your images in the appropriate sub-folder, depending on the platform you
+chose to take the screenshots on.
+

docs/sphinx/rest_substitutions/overviews/index.rst

@@ -126,7 +126,7 @@ project in the `wxWidgets SVN <http://svn.wxwidgets.org/viewvc/wx/wxPython>`_.
 wxPython Documentation
 ----------------------
 
-The new wxPython API documentation is available `in this page <APIMain.html>`_.
+The new wxPython API documentation is available `in this page <main.html>`_.
 
 
 .. toctree::

docs/sphinx/rest_substitutions/overviews/treectrl_overview.rst

@@ -0,0 +1,69 @@
+.. include:: headings.inc
+
+
+.. _treectrl overview:
+
+===============================================
+|phoenix_title|  **TreeCtrl Overview**
+===============================================
+
+The tree control displays its items in a tree like structure. Each item has its own (optional) icon 
+and a label. An item may be either collapsed (meaning that its children are not visible) or expanded 
+(meaning that its children are shown). Each item in the tree is identified by its itemId which is of 
+opaque data type :ref:`TreeItemId`. You can test whether an item is valid by calling :meth:`TreeItemId.IsOk`.
+
+The items text and image may be retrieved and changed with `(Get|Set)ItemText` and `(Get|Set)ItemImage`. 
+In fact, an item may even have two images associated with it: the normal one and another one for selected 
+state which is set/retrieved with `(Get|Set)ItemSelectedImage` functions, but this functionality might 
+be unavailable on some platforms.
+
+Tree items have several attributes: an item may be selected or not, visible or not, bold or not. It may 
+also be expanded or collapsed. All these attributes may be retrieved with the corresponding functions: 
+:meth:`TreeCtrl.IsSelected`, :meth:`TreeCtrl.IsVisible`, :meth:`TreeCtrl.IsBold` and :meth:`TreeCtrl.IsExpanded`. 
+Only one item at a time may be selected, selecting another one (with :meth:`TreeCtrl.SelectItem`) automatically 
+unselects the previously selected one.
+
+In addition to its icon and label, a user-specific data structure may be associated with all tree items. 
+If you wish to do it, you should derive a class from :ref:`TreeItemData` which is a very simple class 
+having only one function `GetId()` which returns the id of the item this data is associated with. This data 
+will be freed by the control itself when the associated item is deleted (all items are deleted when the 
+control is destroyed), so you shouldn't delete it yourself (if you do it, you should call `SetItemData(None)` 
+to prevent the tree from deleting the pointer second time). The associated data may be retrieved with 
+:meth:`TreeCtrl.GetItemData` function.
+
+Working with trees is relatively straightforward if all the items are added to the tree at the moment of 
+its creation. However, for large trees it may be very inefficient. To improve the performance you may want 
+to delay adding the items to the tree until the branch containing the items is expanded: so, in the 
+beginning, only the root item is created (with :meth:`TreeCtrl.AddRoot`). Other items are added when 
+``EVT_TREE_ITEM_EXPANDING`` event is received: then all items lying immediately under the item being expanded 
+should be added, but, of course, only when this event is received for the first time for this item - otherwise, 
+the items would be added twice if the user expands/collapses/re-expands the branch.
+
+The tree control provides functions for enumerating its items. There are 3 groups of enumeration functions: for 
+the children of a given item, for the sibling of the given item and for the visible items (those which are 
+currently shown to the user: an item may be invisible either because its branch is collapsed or because it 
+is scrolled out of view). Child enumeration functions require the caller to give them a `cookie` parameter: it 
+is a number which is opaque to the caller but is used by the tree control itself to allow multiple enumerations 
+to run simultaneously (this is explicitly allowed). The only thing to remember is that the `cookie` passed 
+to :meth:`TreeCtrl.GetFirstChild` and to :meth:`TreeCtrl.GetNextChild` should be the same variable (and that 
+nothing should be done with it by the user code).
+
+Among other features of the tree control are: 
+
+* Item Sorting with :meth:`TreeCtrl.SortChildren` which uses the user-defined comparison function `OnCompareItems` 
+  (by default the comparison is the alphabetic comparison of tree labels);
+* Hit Testing (determining to which portion of the control the given point belongs, useful for implementing 
+  drag-and-drop in the tree) with :meth:`TreeCtrl.HitTest`;
+* Editing of the tree item labels in place (see :meth:`TreeCtrl.EditLabel`).
+
+Finally, the tree control has a keyboard interface: the cursor navigation (arrow) keys may be used to change 
+the current selection. ``HOME`` and ``END`` are used to go to the first/last sibling of the current item. ``+``, 
+``-`` and ``*`` expand, collapse and toggle the current branch. Note, however, that ``DEL`` and ``INS`` keys 
+do nothing by default, but it is common to associate them with deleting an item from a tree and inserting 
+a new one into it.
+
+
+.. seealso:: :ref:`TreeCtrl`, :ref:`ImageList`
+
+
+

docs/sphinx/rest_substitutions/snippets/python/contrib/GridBagSizer.1.py

@@ -0,0 +1,46 @@
+##Chris Barker
+#!/usr/bin/env python
+
+"""
+A simple test of the GridBagSizer
+
+http://wiki.wxpython.org/index.cgi/WriteItYourself
+
+"""
+
+import wx
+
+class MyFrame(wx.Frame):
+    def __init__(self, parent, ID, title):
+        wx.Frame.__init__(self, parent, ID, title, wx.DefaultPosition)
+
+        Buttons = []
+        for i in range(6):
+            Buttons.append(wx.Button(self,-1, "Button %i"%(i)))
+
+        sizer = wx.GridBagSizer(9, 9)
+        sizer.Add(Buttons[0], (0, 0), wx.DefaultSpan,  wx.ALL, 5)
+        sizer.Add(Buttons[1], (1, 1), (1,7), wx.EXPAND)
+        sizer.Add(Buttons[2], (6, 6), (3,3), wx.EXPAND)
+        sizer.Add(Buttons[3], (3, 0), (1,1), wx.ALIGN_CENTER)
+        sizer.Add(Buttons[4], (4, 0), (1,1), wx.ALIGN_LEFT)
+        sizer.Add(Buttons[5], (5, 0), (1,1), wx.ALIGN_RIGHT)
+
+        sizer.AddGrowableRow(6)
+        sizer.AddGrowableCol(6)
+
+        self.SetSizerAndFit(sizer)
+        self.Centre()
+
+
+class MyApp(wx.App):
+    def OnInit(self):
+        frame = MyFrame(None, -1, "wx.gridbagsizer.py")
+        frame.Show(True)
+        self.SetTopWindow(frame)
+        return True
+
+if __name__ == "__main__":
+    app = MyApp(0)
+    app.MainLoop()
+

docs/sphinx/rest_substitutions/snippets/python/contrib/GridBagSizer.2.py

@@ -0,0 +1,43 @@
+##Chris Barker
+#!/usr/bin/env python
+
+import wx
+
+class TestFrame(wx.Frame):
+    def __init__(self, *args, **kwargs):
+        wx.Frame.__init__(self, *args, **kwargs)
+
+        t = wx.TextCtrl(self)
+
+        b1 = wx.Button(self, label="Button1")
+        b2 = wx.Button(self, label="Button2")
+
+        exitBut = wx.Button(self, label="Exit")
+        exitBut.Bind(wx.EVT_BUTTON, self.OnCloseWindow)
+
+        sizer = wx.GridBagSizer(10, 10)
+        sizer.Add(t,  (0,0), span=(2,1), flag=wx.ALIGN_CENTER_VERTICAL )
+        sizer.Add(b1, (0,1), span=(2,1), flag=wx.ALIGN_CENTER)
+        sizer.Add(b2, (0,2), flag=wx.ALIGN_CENTER)
+
+        sizer.Add(exitBut, (1,3))
+
+        self.SetSizerAndFit(sizer)
+
+        wx.EVT_CLOSE(self, self.OnCloseWindow)
+
+    def OnCloseWindow(self, event):
+        self.Destroy()
+
+class App(wx.App):
+    def OnInit(self):
+        frame = TestFrame(None, title="GridBagSizer Test")
+        self.SetTopWindow(frame)
+        frame.Show(True)
+        return True
+
+if __name__ == "__main__":
+    app = App(0)
+    app.MainLoop()
+
+

etg/_core.py

@@ -21,6 +21,7 @@ DOCSTRING = ""
 ITEMS  = [ ]    
 
 
+
 # The list of other ETG scripts and back-end generator modules that are
 # included as part of this module. These items are in their own etg scripts
 # for easier maintainability, but their class and function definitions are
@@ -228,7 +229,14 @@ def run():
             method calls from non-GUI threads.  Any extra positional or
             keyword args are passed on to the callable when it is called.
             
-            :see: `CallLater`""",
+            :param callableObj: the callable object
+            :param args: arguments to be passed to the callable object
+            :param kw: keywords to be passed to the callable object
+            
+            .. seealso::
+                :class:`CallLater`
+            
+            """,
         body="""\
             assert callable(callableObj), "callableObj is not callable"
             app = wx.GetApp()
@@ -260,7 +268,15 @@ def run():
             the timer completes, automatically cleaning up the wx.CallLater
             object.
             
-            :see: `CallAfter`""",
+            :param int millis: number of milli seconds
+            :param callableObj: the callable object
+            :param args: arguments to be passed to the callable object
+            :param kw: keywords to be passed to the callable object
+            
+            ::seealso:
+                :func:`CallAfter`
+                
+            """,
         items = [
             PyFunctionDef('__init__', '(self, millis, callableObj, *args, **kwargs)',
                 body="""\
@@ -278,7 +294,14 @@ def run():
             PyFunctionDef('__del__', '(self)', 'self.Stop()'),
             
             PyFunctionDef('Start', '(self, millis=None, *args, **kwargs)', 
-                doc="(Re)start the timer",
+                doc="""\
+                    (Re)start the timer
+
+                    :param int millis: number of milli seconds
+                    :param args: arguments to be passed to the callable object
+                    :param kw: keywords to be passed to the callable object
+
+                    """,
                 body="""\
                     self.hasRun = False
                     if millis is not None:
@@ -312,13 +335,27 @@ def run():
                     (Re)set the args passed to the callable object.  This is
                     useful in conjunction with Restart if you want to schedule a
                     new call to the same callable object but with different
-                    parameters.""",
+                    parameters.
+
+                    :param args: arguments to be passed to the callable object
+                    :param kw: keywords to be passed to the callable object
+                    
+                    """,
                 body="""\
                     self.args = args
                     self.kwargs = kwargs"""),
             
-            PyFunctionDef('HasRun', '(self)', 'return self.hasRun'),
-            PyFunctionDef('GetResult', '(self)', 'return self.result'),
+            PyFunctionDef('HasRun', '(self)', 'return self.hasRun',
+                doc="""\
+                    :rtype: boolean
+                    
+                    """),
+
+            PyFunctionDef('GetResult', '(self)', 'return self.result',
+                doc="""\
+                    :rtype: result from callable
+                    
+                    """),
 
             PyFunctionDef('Notify', '(self)', 
                 doc="The timer has expired so call the callable.",

etg/app.py

@@ -343,7 +343,7 @@ def run():
                         app to terminate upon a Ctrl-C in the console like other
                         GUI apps will.
             
-                    :note: You should override OnInit to do applicaition
+                    :note: You should override OnInit to do application
                         initialization to ensure that the system, toolkit and
                         wxWidgets are fully initialized.
                     """,

etgtools/sphinx_generator.py

@@ -20,6 +20,7 @@ import os
 import operator
 import shutil
 import textwrap
+import glob
 
 from StringIO import StringIO
 
@@ -41,6 +42,7 @@ from sphinxtools.utilities import FindControlImages, MakeSummary, PickleItem
 from sphinxtools.utilities import ChopDescription, PythonizeType, Wx2Sphinx
 from sphinxtools.utilities import PickleClassInfo, IsNumeric
 from sphinxtools.utilities import Underscore2Capitals, CountSpaces
+from sphinxtools.utilities import FormatContributedSnippets
 
 from sphinxtools.constants import VERSION, REMOVED_LINKS, SECTIONS
 from sphinxtools.constants import MAGIC_METHODS, MODULENAME_REPLACE
@@ -1578,6 +1580,8 @@ class ComputerOutput(Node):
             text += ConvertToPython(self.element.tail)
 
         space_before, space_after = CountSpaces(text)
+        if space_before == '':
+            space_before = ' '
 
         return space_before + text + space_after
 
@@ -1626,13 +1630,41 @@ class Emphasis(Node):
 
         if self.element.tag == 'emphasis':
             format = '`%s`'
+            emphasys = '`'
         elif self.element.tag == 'bold':
             format = '**%s**'
+            emphasys = '**'
 
         spacing = ('ParameterList' in self.GetHierarchy() and [' '] or [''])[0]
 
         text = Node.Join(self, with_tail=False)
 
+        if self.children:
+
+            startPos = 0
+            newText = spacing
+
+            for child in self.children:
+                childText = child.Join()
+
+                tail = child.element.tail
+                tail = (tail is not None and [tail] or [''])[0]
+
+                childText = childText.replace(ConvertToPython(tail), '')
+                fullChildText = child.Join()
+                endPos = text.index(childText)
+
+                newText += ' ' + emphasys + text[startPos:endPos].strip() + emphasys + ' '
+                newText += childText + ' '
+                remaining = fullChildText.replace(childText, '')
+                newText += emphasys + remaining.strip() + emphasys + ' '
+                
+                startPos = endPos
+
+            text = newText
+            
+        else:
+            
             if text.strip():
                 text = spacing + format % text.strip()
 
@@ -1776,6 +1808,8 @@ class XMLDocString(object):
         self.class_name = ''
         
         self.snippet_count = 0
+        self.contrib_snippets = []
+
         self.table_count = 0
 
         self.list_level = 1        
@@ -2050,13 +2084,29 @@ class XMLDocString(object):
             dummy, fullname = Wx2Sphinx(name)
         elif self.kind == 'method':
             method = self.xml_item
-            if method.isCtor:
+            if hasattr(method, 'isCtor') and method.isCtor:
                 method_name = '__init__'
+                
+                if hasattr(method, 'className') and method.className is not None:
+                    klass = RemoveWxPrefix(method.className)
+                else:
+                    klass = RemoveWxPrefix(method.klass.name)
+                    
+                method_name = '%s.%s'%(klass, method_name)
             else:
                 method_name = method.name or method.pyName
+                if hasattr(method, 'className') and method.className is not None:
+                    klass = RemoveWxPrefix(method.className)
+                    method_name = '%s.%s'%(klass, method_name)
+                elif hasattr(method, 'klass'):
+                    klass = RemoveWxPrefix(method.klass.name)
+                    method_name = '%s.%s'%(klass, method_name)
+                else:
                     method_name = RemoveWxPrefix(method_name)
-            dummy, fullname = Wx2Sphinx(method.className)
-            fullname = fullname + '.' + method_name
+                    method_name = '%s'%method_name
+                    klass = None
+
+            dummy, fullname = Wx2Sphinx(method_name)
         elif self.kind == 'function':
             function = self.xml_item
             name = function.pyName or function.name
@@ -2092,6 +2142,16 @@ class XMLDocString(object):
         return cpp_file, python_file, converted_py
 
 
+    def HuntContributedSnippets(self):
+        
+        fullname = self.GetFullName()
+        contrib_folder = os.path.join(SNIPPETROOT, 'python', 'contrib')
+
+        possible_py = glob.glob(os.path.normpath(contrib_folder + '/' + fullname + '*.py'))
+
+        return possible_py
+                
+
     # -----------------------------------------------------------------------
 
     def Dump(self, write=True):
@@ -2159,6 +2219,13 @@ class XMLDocString(object):
             subs_desc = templates.TEMPLATE_SUBCLASSES % subs
             stream.write(subs_desc)
 
+        possible_py = self.HuntContributedSnippets()
+        
+        if possible_py:
+            possible_py.sort()
+            snippets = FormatContributedSnippets(self.kind, possible_py)
+            stream.write(snippets)
+
         if klass.method_list:
             summary = MakeSummary(name, klass.method_list, templates.TEMPLATE_METHOD_SUMMARY, 'meth')
             stream.write(summary)
@@ -2381,6 +2448,14 @@ class XMLDocString(object):
         stream.write('\n\n')
 
         self.Reformat(stream)
+
+        possible_py = self.HuntContributedSnippets()
+        
+        if possible_py:
+            possible_py.sort()
+            snippets = FormatContributedSnippets(self.kind, possible_py)
+            stream.write(snippets)
+
         stream.write("\n\n")
 
         if not self.is_overload and write:
@@ -2418,6 +2493,13 @@ class XMLDocString(object):
 
         self.Reformat(stream)
 
+        possible_py = self.HuntContributedSnippets()
+        
+        if possible_py:
+            possible_py.sort()
+            snippets = FormatContributedSnippets(self.kind, possible_py)
+            stream.write(snippets)
+
         if not self.is_overload and write:        
             PickleItem(stream.getvalue(), self.current_module, name, 'function')
 
@@ -2494,6 +2576,9 @@ class XMLDocString(object):
         newline = line
 
         if 'supports the following styles:' in line:
+            if class_name is not None:
+                # Crappy wxWidgets docs!!! They put the Window Styles inside the
+                # constructor!!!
                 docstrings += templates.TEMPLATE_WINDOW_STYLES % class_name
                 
         elif 'The following event handler macros' in line:
@@ -2935,11 +3020,17 @@ class SphinxGenerator(generators.DocsGeneratorBase):
         stream = StringIO()
         stream.write('\n   .. method:: %s%s\n\n' % (pm.name, pm.argsString))
 
-        docstrings = ConvertToPython(pm.pyDocstring).replace('\n', ' ')
+##        docstrings = ConvertToPython(pm.pyDocstring).replace('\n', ' ')
+        docstrings = ConvertToPython(pm.pyDocstring)
 
         newdocs = ''
+        spacer = ' '*6
+        
         for line in docstrings.splitlines():
-            newdocs += ' '*6 + line + "\n"
+            if not line.startswith(spacer):
+                newdocs += spacer + line + "\n"
+            else:
+                newdocs += line + "\n"
                 
         stream.write(newdocs + '\n\n')
 

sphinxtools/constants.py

@@ -144,7 +144,7 @@ HTML_REPLACE = ['module', 'function', 'method', 'class', 'classmethod', 'staticm
 
 # The SVN revision of wxWidgets/Phoenix used to build the Sphinx docs.
 # There must be a more intelligent way to get this information automatically.
-SVN_REVISION = '71022'
+SVN_REVISION = '71066'
 
 # Today's date representation for the Sphinx HTML docs
 TODAY = datetime.date.today().strftime('%d %B %Y')

sphinxtools/postprocess.py

@@ -145,6 +145,9 @@ def BuildEnumsAndMethods(sphinxDir):
         text = text.replace(':note:', '.. note::')
         text = text.replace(':see:', '.. seealso::')
         text = text.replace('`String`&', 'string')
+        text = text.replace('See also\n', '.. seealso:: ')
+        # Avoid Sphinx warnings on wx.TreeCtrl
+        text = text.replace('**( `', '** ( `')
             
         if text != orig_text:
             fid = open(input, 'wt')
@@ -185,7 +188,13 @@ def BuildEnumsAndMethods(sphinxDir):
 
 def FindInherited(input, class_summary, enum_base, text):
 
-    regex = re.findall(':meth:\S+', text)
+    # Malformed inter-links
+    regex = re.findall(r'\S:meth:\S+', text)
+    for regs in regex:
+        newreg = regs[0] + ' ' + regs[1:]
+        text = text.replace(regs, newreg)
+
+    regex = re.findall(r':meth:\S+', text)
 
     for regs in regex:
         
@@ -304,20 +313,25 @@ def ReformatFunctions(file):
         label = local_file.split('.')[0:-2][0]
 
     names = functions.keys()
+    names = [name.lower() for name in names]
     names.sort()
 
     text = templates.TEMPLATE_FUNCTION_SUMMARY % (label, label)
 
     letters = []
     for fun in names:
-        if fun[0] not in letters:
-            letters.append(fun[0].upper())
+        upper = fun[0].upper()
+        if upper not in letters:
+            letters.append(upper)
 
-    text += '  |  '.join(['`%s`_'%letter for letter in letters])
+    text += '  |  '.join([':ref:`%s <%s %s>`'%(letter, label, letter) for letter in letters])
     text += '\n\n\n'
 
+    names = functions.keys()
+    names = sorted(names, key=str.lower)
+
     for letter in letters:
-        text += '%s\n^\n\n'%letter
+        text += '.. _%s %s:\n\n%s\n^\n\n'%(label, letter, letter)
         for fun in names:
             if fun[0].upper() != letter:
                 continue

sphinxtools/templates.py

@@ -198,6 +198,12 @@ TEMPLATE_EVENTS = '''
 
 '''
 
+TEMPLATE_CONTRIB = '''
+
+|user| Contributed Examples
+===========================
+
+'''
 
 # Template used to generate the widgets gallery (this needs some work)
 TEMPLATE_GALLERY = '''

sphinxtools/utilities.py

@@ -19,6 +19,8 @@ import cPickle
 from UserDict import UserDict
 
 # Phoenix-specific imports
+from templates import TEMPLATE_CONTRIB
+
 from constants import IGNORE, PUNCTUATION
 from constants import CPP_ITEMS, VERSION, VALUE_MAP
 from constants import RE_KEEP_SPACES
@@ -587,3 +589,31 @@ def Wx2Sphinx(name):
 
 
 # ----------------------------------------------------------------------- #
+
+def FormatContributedSnippets(kind, contrib_snippets):
+
+    spacer = ''
+    if kind == 'function':
+        spacer = 3*' '
+    elif kind == 'method':
+        spacer = 6*' '
+
+    if kind == 'class':
+        text = TEMPLATE_CONTRIB
+    else:
+        text = spacer + '\n**Contributed Examples:**\n\n'
+    
+    for indx, snippet in enumerate(contrib_snippets):
+        fid = open(snippet, 'rt')
+        lines = fid.readlines()
+        fid.close()
+        user = lines[0].replace('##', '').strip()
+
+        text += '\n' + spacer + 'Example %d (%s)::\n\n'%(indx+1, user)
+
+        for line in lines[1:]:
+            text += 4*' '+ spacer + line
+
+        text += '\n'
+
+    return text