Phoenix: few corrections to the overviews; Added some more contributed snippets; Fixed some more converted snippets; Added the correct interlink references in the etg files; better handling of the Doxygen stuff.

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

docs/sphinx/_downloads/TreeCtrl.OnCompareItems.1.py

@@ -0,0 +1,13 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to override OnCompareItems for wx.TreeCtrl.
+# The overridden method simply compares lowercase item texts
+
+def OnCompareItems(self, item1, item2):
+    """Changes the sort order of the items in the tree control. """
+    
+    t1 = self.GetItemText(item1)
+    t2 = self.GetItemText(item2)
+
+    return cmp(t1.lower(), t2.lower())

docs/sphinx/rest_substitutions/overviews/dialog_overview.rst

@@ -98,5 +98,5 @@ PropertySheetDialog and Wizard
 Adaptation for :ref:`PropertySheetDialog` is always done by simply making the pages scrollable, since :meth:`Dialog.GetContentWindow` returns the dialog's 
 book control and this is handled by the standard layout adapter.
 
-:ref:`Wizard` uses its own `CanDoLayoutAdaptation` and `DoLayoutAdaptation` functions rather than the global adapter: again, only the wizard pages are made scrollable.
+:class:`~adv.Wizard` uses its own `CanDoLayoutAdaptation` and `DoLayoutAdaptation` functions rather than the global adapter: again, only the wizard pages are made scrollable.
 

docs/sphinx/rest_substitutions/overviews/events_overview.rst

@@ -74,7 +74,7 @@ Event handlers can be bound at any moment. For example, it's possible to do some
 handlers if and when it succeeds. This can avoid the need to test that the object was properly initialized in the event 
 handlers themselves. With `Bind()` they simply won't be called if it wasn't correctly initialized.
 
-As a slight extension of the above, the handlers can also be unbound at any time with `Unbind()` (and maybe rebound later). 
+As a slight extension of the above, the handlers can also be unbound at any time with :meth:`EvtHandler.Unbind` () (and maybe rebound later). 
 
 Almost last but very, very far from least is the flexibility which allows to bind an event to:
 
@@ -89,9 +89,10 @@ first one for the object methods and the other one for arbitrary functors (calla
 In addition to using a method of the object generating the event itself, you can use a method from a completely different
 object as an event handler::
 
-	def OnFrameExit(event)
+	def OnFrameExit(event):
 
 	    # Do something useful.
+		pass
 
 
 	class MyFrame(wx.Frame):
@@ -283,7 +284,7 @@ events. The only exceptions to this rule are:
 
 
 :meth:`TextEntry.ChangeValue` can be used instead of :meth:`TextEntry.SetValue` but the other functions, such as :meth:`TextEntry.Replace`
-or meth:`TextCtrl.WriteText` don't have event-free equivalents.
+or :meth:`TextCtrl.WriteText` don't have event-free equivalents.
 
 
 

docs/sphinx/rest_substitutions/overviews/filesystem_overview.rst

@@ -31,9 +31,9 @@ Locations
 
 Locations (aka filenames aka addresses) are constructed from four parts:
 
-* **protocol** - handler can recognize if it is able to open a file by checking its protocol. Examples are "http", "file" or "ftp".
+* **protocol** - handler can recognize if it is able to open a file by checking its protocol. Examples are ``"http"``, ``"file"`` or ``"ftp"``.
-* **right location** - is the name of file within the protocol. In "http://www.wxwidgets.org/index.html" the right location is "//www.wxwidgets.org/index.html".
+* **right location** - is the name of file within the protocol. In ``"http://www.wxwidgets.org/index.html"`` the right location is ``"//www.wxwidgets.org/index.html"``.
-* **anchor** - an anchor is optional and is usually not present. In "index.htm#chapter2" the anchor is "chapter2".
+* **anchor** - an anchor is optional and is usually not present. In ``"index.htm#chapter2"`` the anchor is ``"chapter2"``.
 * **left location** - this is usually an empty string. It is used by 'local' protocols such as ZIP. See the :ref:`Combined Protocols <combined protocols>` paragraph for details.
 
 
@@ -48,7 +48,7 @@ It is not used by global protocols like HTTP but it becomes handy when nesting p
 
 ``file:archives/cpp_doc.zip#zip:reference/fopen.htm#syntax`` 
 
-In this example, the protocol is "zip", right location is "reference/fopen.htm", anchor is "syntax" and left location is ``file:archives/cpp_doc.zip``.
+In this example, the protocol is ``"zip"``, right location is ``"reference/fopen.htm"``, anchor is ``"syntax"`` and left location is ``file:archives/cpp_doc.zip``.
 
 There are two protocols used in this example: "zip" and "file".
 
@@ -60,11 +60,11 @@ File Systems Included in wxHTML
 
 The following virtual file system handlers are part of wxPython so far:
 
-* :ref:`ArchiveFSHandler`: A handler for archives such as zip and tar. URLs examples: "archive.zip#zip:filename", "archive.tar.gz#gzip:#tar:filename".
+* :ref:`ArchiveFSHandler`: A handler for archives such as zip and tar. URLs examples: ``"archive.zip#zip:filename"``, ``"archive.tar.gz#gzip:#tar:filename"``.
-* :ref:`FilterFSHandler`: A handler for compression schemes such as gzip. URLs are in the form, e.g.: "document.ps.gz#gzip:".
+* :ref:`FilterFSHandler`: A handler for compression schemes such as gzip. URLs are in the form, e.g.: ``"document.ps.gz#gzip:"``.
 * :ref:`InternetFSHandler`: A handler for accessing documents via HTTP or FTP protocols.
 * :ref:`MemoryFSHandler`: This handler allows you to access data stored in memory (such as bitmaps) as if they were regular files. See :ref:`MemoryFSHandler` for details. 
-  URL is prefixed with memory:, e.g. "memory:myfile.htm".
+  URL is prefixed with memory:, e.g. ``"memory:myfile.htm"``.
   
 
 In addition, :ref:`FileSystem` itself can access local files.

docs/sphinx/rest_substitutions/overviews/html_overview.rst

@@ -86,7 +86,7 @@ You can customize :class:`~html.HtmlWindow` by setting font size, font face and
 -   :meth:`~html.HtmlWindow.ReadCustomization`
 -   :meth:`~html.HtmlWindow.WriteCustomization`
 
-The last two functions are used to store user customization info :class:`Config`
+The last two functions are used to store user customization info :class:`ConfigBase`
 stuff (for example in the registry under Windows, or in a dotfile under
 Unix).
 

docs/sphinx/rest_substitutions/overviews/tipprovider_overview.rst

@@ -21,18 +21,18 @@ feature is extremely easy. To show a tip, it is enough to just call :func:`ShowT
 
 
 Of course, you need to get the text of the tips from somewhere - in the example above, the text is supposed to be in the
-file `tips.txt` from where it is read by the tip provider. The tip provider is just an object of a class deriving from :class:`TipProvider`. 
+file `tips.txt` from where it is read by the tip provider. The tip provider is just an object of a class deriving from :class:`~adv.TipProvider`. 
 It has to implement one pure virtual function of the base class, `GetTip`. In the case of the tip provider created by 
 :func:`CreateFileTipProvider`, the tips are just the lines of the text file.
 
 If you want to implement your own tip provider (for example, if you wish to hardcode the tips inside your program), you 
-just have to derive another class from :class:`TipProvider` and pass a pointer to the object of this class to func:`ShowTip` - then 
+just have to derive another class from :class:`~adv.TipProvider` and pass a pointer to the object of this class to func:`ShowTip` - then 
 you don't need :func:`CreateFileTipProvider` at all.
 
 You will probably want to save somewhere the index of the tip last shown - so that the program doesn't always show the same 
 tip on startup. As you also need to remember whether to show tips or not (you shouldn't do it if the user unchecked 
 "Show tips on startup" checkbox in the dialog), you will probably want to store both the index of the last shown tip 
-(as returned by :meth:`TipProvider.GetCurrentTip` and the flag telling whether to show the tips at startup at all.
+(as returned by :meth:`~adv.TipProvider.GetCurrentTip` and the flag telling whether to show the tips at startup at all.
 
 In a `tips.txt` file, lines that begin with a ``#`` character are considered comments and are automatically skipped. Blank 
 lines and lines only having spaces are also skipped.

docs/sphinx/rest_substitutions/snippets/python/contrib/TreeCtrl.OnCompareItems.1.py

@@ -0,0 +1,13 @@
+##Andrea Gavana
+#!/usr/bin/env python
+
+# This sample shows how to override OnCompareItems for wx.TreeCtrl.
+# The overridden method simply compares lowercase item texts
+
+def OnCompareItems(self, item1, item2):
+    """Changes the sort order of the items in the tree control. """
+    
+    t1 = self.GetItemText(item1)
+    t2 = self.GetItemText(item2)
+
+    return cmp(t1.lower(), t2.lower())

docs/sphinx/rest_substitutions/snippets/python/converted/TimerEvent.1.py

@@ -14,6 +14,6 @@
             def OnTimer(self, event):
         
                 # do whatever you want to do every second here
-                print 'Hello'
+                print('Hello')
                 
         

docs/sphinx/rest_substitutions/snippets/python/converted/VListBox.GetFirstSelected.1.py

@@ -1,6 +1,6 @@
     
             item, cookie = vlbox.GetFirstSelected()
-            while item != wx.NOT_FOUND
+            while item != wx.NOT_FOUND:
                 # ... process item ...
                 item, cookie = vlbox.GetNextSelected(cookie)
             

docs/sphinx/rest_substitutions/snippets/python/converted/Window.SetBackgroundStyle.1.py

@@ -3,14 +3,13 @@
 
             def __init__(self, parent):    
 
-                pre = wx.PreWindow() # Use Pre- constructor here!
+                wx.Window.__init__(self) # Use default constructor here!
             
                 # Do this first:
                 self.SetBackgroundStyle(wx.BG_STYLE_TRANSPARENT)
 
                 # And really create the window afterwards:
-                pre.Create(parent)
+                self.Create(parent)
-                self.PostCreate(pre)
 
         
                     

docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.Draw.1.py

@@ -1,3 +1,3 @@
     
     
-        dc.DrawText("hello", x + self.PosX, y + self.PosY)
+        dc.DrawText("hello", x + cell.PosX, y + cell.PosY)

docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.DrawInvisible.1.py

@@ -1,3 +1,3 @@
 
     
-        dc.DrawText("hello", x + self.PosX, y + self.PosY)
+        dc.DrawText("hello", x + cell.PosX, y + cell.PosY)

docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlHelpWindow.1.py

@@ -8,5 +8,5 @@
             self.embeddedHtmlHelp.UseConfig(config, rootPath) # Set your own config object here
             self.embeddedHtmlHelp.SetHelpWindow(self.embeddedHelpWindow)
             self.embeddedHelpWindow.Create(self, wx.ID_ANY, wx.DefaultPosition, self.GetClientSize(),
-                                           wx.TAB_TRAVERSAL|wx.BORDER_NONE, wx.html.HF_DEFAULT_STYLE)
+                                           wx.TAB_TRAVERSAL | wx.BORDER_NONE, wx.html.HF_DEFAULT_STYLE)
             self.embeddedHtmlHelp.AddBook("doc.zip")

docs/sphinx/rest_substitutions/tables/VScrolledWindow.1.rst

@@ -3,7 +3,7 @@
 `GetLastVisibleLine()`                  Deprecated for :meth:`~VarVScrollHelper.GetVisibleRowsEnd` This function originally had a slight design flaw in that it was possible to return ``sys.maxint-1``   (ie: a large positive number) if the scroll position was 0 and the first line wasn't completely visible.       
 `GetLineCount()`                        Deprecated for :meth:`~VarVScrollHelper.GetRowCount`                                                                                                                                                                                                                           
 `HitTest(x, y)`
-`HitTest(pt)`                           Deprecated for :meth:`~VScrolledWindow.VirtualHitTest`.                                                                                                                                                                                                                        
+`HitTest(pt)`                           Deprecated for :meth:`~VarScrollHelperBase.VirtualHitTest`.                                                                                                                                                                                                                        
 `OnGetLineHeight(line)`                 Deprecated for :meth:`~VarVScrollHelper.OnGetRowHeight`                                                                                                                                                                                                                        
 `OnGetLinesHint(lineMin, lineMax)`      Deprecated for :meth:`~VarVScrollHelper.OnGetRowsHeightHint`                                                                                                                                                                                                                   
 `RefreshLine(line)`                     Deprecated for :meth:`~VarVScrollHelper.RefreshRow`                                                                                                                                                                                                                            

etg/_core.py

@@ -435,7 +435,7 @@ def run():
         """)
 
     module.addCppFunction('bool', 'IsMainThread', '()',
-        doc="Returns True if the current thread is what wx considers the GUI thread.",
+        doc="Returns ``True`` if the current thread is what wx considers the GUI thread.",
         body="return wxThread::IsMain();")
     
 

etg/checklst.py

@@ -46,7 +46,7 @@ def run():
         GetChecked()
     
         Return a sequence of integers corresponding to the checked items in
-        the control, based on `IsChecked`.""",
+        the control, based on :meth:`IsChecked`.""",
         body="return tuple([i for i in range(self.Count) if self.IsChecked(i)])")
 
     c.addPyMethod('GetCheckedStrings', '(self)', 
@@ -54,7 +54,7 @@ def run():
             GetCheckedStrings()
      
             Return a tuple of strings corresponding to the checked
-            items of the control, based on `GetChecked`.""",
+            items of the control, based on :meth:`GetChecked`.""",
         body="return tuple([self.GetString(i) for i in self.GetChecked()])")
     
     c.addPyMethod('SetChecked', '(self, indexes)', 

etg/ctrlsub.py

@@ -67,10 +67,10 @@ def run():
     c.find('GetClientObject').pyName = 'GetClientData'
     c.find('SetClientObject').pyName = 'SetClientData'
     c.addPyMethod('GetClientObject', '(self, n)', 
-        doc="alias for GetClientData",
+        doc="Alias for :meth:`GetClientData`",
         body="return self.GetClientData(n)")
     c.addPyMethod('SetClientObject', '(self, n, data)', 
-        doc="alias for SetClientData",
+        doc="Alias for :meth:`SetClientData`",
         body="self.SetClientData(n, data)")
     
     

etg/dataview.py

@@ -113,20 +113,20 @@ def run():
     module.addPyClass('DataViewItemObjectMapper', ['object'],
         doc="""\
             This class provides a mechanism for mapping between Python objects and the
-            DataViewItem objects used by the DataViewModel for tracking the items in
+            :class:`DataViewItem` objects used by the :class:`DataViewModel` for tracking the items in
             the view. The ID used for the item is the id() of the Python object. Use
-            `ObjectToItem` to create a DataViewItem using a Python object as its ID,
+            :meth:`ObjectToItem` to create a :class:`DataViewItem` using a Python object as its ID,
-            and use `ItemToObject` to fetch that Python object again later for a given
+            and use :meth:`ItemToObject` to fetch that Python object again later for a given
-            DataViewItem.
+            :class:`DataViewItem`.
     
             By default a regular dictionary is used to implement the ID to object
             mapping. Optionally a WeakValueDictionary can be useful when there will be
             a high turnover of objects and mantaining an extra reference to the
             objects would be unwise.  If weak references are used then the objects
             associated with data items must be weak-referenceable.  (Things like
-            stock lists and dictionaries are not.)  See `UseWeakRefs`.
+            stock lists and dictionaries are not.)  See :meth:`UseWeakRefs`.
             
-            This class is used in `PyDataViewModel` as a mixin for convenience.
+            This class is used in :class:`PyDataViewModel` as a mixin for convenience.
             """,
         items=[
             PyFunctionDef('__init__', '(self)', 
@@ -136,7 +136,7 @@ def run():
                     """),
             
             PyFunctionDef('ObjectToItem', '(self, obj)',
-                doc="Create a DataViewItem for the object, and remember the ID-->obj mapping.",
+                doc="Create a :class:`DataViewItem` for the object, and remember the ID-->obj mapping.",
                 body="""\
                     oid = id(obj)
                     self.mapper[oid] = obj
@@ -169,7 +169,7 @@ def run():
             ])
 
     module.addPyClass('PyDataViewModel', ['DataViewModel', 'DataViewItemObjectMapper'],
-        doc="A convenience class that is a DataViewModel combined with an object mapper.",
+        doc="A convenience class that is a :class:`DataViewModel` combined with an object mapper.",
         items=[
             PyFunctionDef('__init__', '(self)', 
                 body="""\
@@ -326,7 +326,7 @@ def run():
     c.find('AssociateModel').pyName = '_AssociateModel'
     c.addPyMethod('AssociateModel', '(self, model)', 
         doc="""\
-            Associates a DataViewModel with the control.
+            Associates a :class:`DataViewModel` with the control.
             Ownership of the model object is passed to C++, however it 
             is reference counted so it can be shared with other views.
             """,

etg/datectrl.py

@@ -20,7 +20,7 @@ DOCSTRING = ""
 # this script. 
 ITEMS  = [ "wxDatePickerCtrl",
            ]    
-    
+           
 #---------------------------------------------------------------------------
 
 def run():

etg/event.py

@@ -144,7 +144,7 @@ def run():
             PyFunctionDef('__call__', '(self, *args)',
                 deprecated="Use :meth:`EvtHandler.Bind` instead.",
                 doc="""\
-                    For backwards compatibility with the old EVT_* functions.
+                    For backwards compatibility with the old ``EVT_*`` functions.
                     Should be called with either (window, func), (window, ID,
                     func) or (window, ID1, ID2, func) parameters depending on the
                     type of the event.
@@ -287,11 +287,11 @@ def run():
         doc="""\
             Bind an event to an event handler.
     
-            :param event: One of the EVT_* event binder objects that
+            :param event: One of the ``EVT_*`` event binder objects that
                           specifies the type of event to bind.
         
             :param handler: A callable object to be invoked when the
-                            event is delivered to self.  Pass None to
+                            event is delivered to self.  Pass ``None`` to
                             disconnect an event handler.
         
             :param source: Sometimes the event originates from a
@@ -321,8 +321,8 @@ def run():
     
     c.addPyMethod('Unbind', '(self, event, source=None, id=wx.ID_ANY, id2=wx.ID_ANY, handler=None)',
         doc="""\
-            Disconnects the event handler binding for event from self.
+            Disconnects the event handler binding for event from `self`.
-            Returns True if successful.
+            Returns ``True`` if successful.
             """,
         body="""\
             if source is not None:

etg/listctrl.py

@@ -244,7 +244,7 @@ def run():
 
     # Add some Python helper methods
     c.addPyMethod('Select', '(self, idx, on=1)',
-        doc='[de]select an item',
+        doc='Selects/deselects an item.',
         body="""\
         if on: state = wx.LIST_STATE_SELECTED
         else: state = 0
@@ -252,26 +252,26 @@ def run():
         """)
     
     c.addPyMethod('Focus', '(self, idx)', 
-        doc='Focus and show the given item',
+        doc='Focus and show the given item.',
         body="""\
         self.SetItemState(idx, wx.LIST_STATE_FOCUSED, wx.LIST_STATE_FOCUSED)
         self.EnsureVisible(idx)
         """)
 
     c.addPyMethod('GetFocusedItem', '(self)',
-        doc='get the currently focused item or -1 if none',
+        doc='Gets the currently focused item or -1 if none is focused.',
         body='return self.GetNextItem(-1, wx.LIST_NEXT_ALL, wx.LIST_STATE_FOCUSED)')
 
     c.addPyMethod('GetFirstSelected', '(self, *args)',
-        doc='return first selected item, or -1 when none',
+        doc='Returns the first selected item, or -1 when none is selected.',
         body="return self.GetNextSelected(-1)")
 
     c.addPyMethod('GetNextSelected', '(self, item)',
-        doc='return subsequent selected items, or -1 when no more',
+        doc='Returns subsequent selected items, or -1 when no more are selected.',
         body="return self.GetNextItem(item, wx.LIST_NEXT_ALL, wx.LIST_STATE_SELECTED)")
 
     c.addPyMethod('IsSelected', '(self, idx)',
-        doc='return True if the item is selected',
+        doc='Returns ``True`` if the item is selected.',
         body="return (self.GetItemState(idx, wx.LIST_STATE_SELECTED) & wx.LIST_STATE_SELECTED) != 0")
 
     c.addPyMethod('SetColumnImage', '(self, col, image)',
@@ -294,7 +294,7 @@ def run():
 
     c.addPyMethod('Append', '(self, entry)',
         doc='''\
-        Append an item to the list control.  The entry parameter should be a
+        Append an item to the list control.  The `entry` parameter should be a
         sequence with an item for each column''',
         body="""\
         if len(entry):

etg/menu.py

@@ -103,14 +103,14 @@ def run():
     c.addPyMethod('GetMenus', '(self)', 
         doc="""\
         GetMenus() -> (menu, label)\n
-        Return a list of (menu, label) items for the menus in the MenuBar.""",
+        Return a list of (menu, label) items for the menus in the :class:`MenuBar`.""",
         body="""\
         return [(self.GetMenu(i), self.GetLabelTop(i)) for i in range(self.GetMenuCount())]
         """)    
     c.addPyMethod('SetMenus', '(self, items)', 
         doc="""\
         SetMenus()\n
-        Clear and add new menus to the MenuBar from a list of (menu, label) items.""",
+        Clear and add new menus to the :class:`MenuBar` from a list of (menu, label) items.""",
         body="""\
         for i in range(self.GetMenuCount()-1, -1, -1):
             self.Remove(i)

etg/sizer.py

@@ -94,9 +94,9 @@ def run():
 
     c.addPyMethod('AddMany', '(self, items)', 
         doc="""\
-        AddMany is a convenience method for adding several items to a sizer
+        :meth:`AddMany` is a convenience method for adding several items to a sizer
         at one time. Simply pass it a list of tuples, where each tuple
-        consists of the parameters that you would normally pass to the `Add`
+        consists of the parameters that you would normally pass to the :meth:`Add`
         method.
         """,        
         body="""\
@@ -109,35 +109,35 @@ def run():
     c.addCppMethod('wxSizerItem*', 'Add', 
                    '(const wxSize& size, int proportion=0, int flag=0, '
                    'int border=0, wxPyUserData* userData /Transfer/ = NULL)',
-        doc="Add a spacer using a Size object.",
+        doc="Add a spacer using a :class:`Size` object.",
         body="return self->Add(size->x, size->y, proportion, flag, border, userData);")
 
     c.addCppMethod('wxSizerItem*', 'Prepend', 
                    '(const wxSize& size, int proportion=0, int flag=0, '
                    'int border=0, wxPyUserData* userData /Transfer/ = NULL)',
-        doc="Prepend a spacer using a Size object.",
+        doc="Prepend a spacer using a :class:`Size` object.",
         body="return self->Prepend(size->x, size->y, proportion, flag, border, userData);")
 
     c.addCppMethod('wxSizerItem*', 'Insert', 
                    '(size_t index, const wxSize& size, int proportion=0, int flag=0, '
                    'int border=0, wxPyUserData* userData /Transfer/ = NULL)',
-        doc="Insert a spacer using a Size object.",
+        doc="Insert a spacer using a :class:`Size` object.",
         body="return self->Insert(index, size->x, size->y, proportion, flag, border, userData);")
 
 
     c.addCppMethod('wxSizerItem*', 'Add', 
                    '(const wxSize& size, const wxSizerFlags& flags)',
-        doc="Add a spacer using a Size object.",
+        doc="Add a spacer using a :class:`Size` object.",
         body="return self->Add(size->x, size->y, *flags);")
 
     c.addCppMethod('wxSizerItem*', 'Prepend', 
                    '(const wxSize& size, const wxSizerFlags& flags)',
-        doc="Prepend a spacer using a Size object.",
+        doc="Prepend a spacer using a :class:`Size` object.",
         body="return self->Prepend(size->x, size->y, *flags);")
 
     c.addCppMethod('wxSizerItem*', 'Insert', 
                    '(size_t index, const wxSize& size, const wxSizerFlags& flags)',
-        doc="Insert a spacer using a Size object.",
+        doc="Insert a spacer using a :class:`Size` object.",
         body="return self->Insert(index, size->x, size->y, *flags);")
 
 

etg/window.py

@@ -162,7 +162,7 @@ def run():
 
     c.addPyMethod('__nonzero__', '(self)',
         doc="Can be used to test if the C++ part of the window still exists, with \n"
-            "code like this:\n\n"
+            "code like this::\n\n"
             "    if theWindow:\n"
             "        doSomething()",
         body="""\

etg/wxdatetime.py

@@ -81,12 +81,12 @@ def run():
     # Add static factories for some of the ctors we ignored
     c.addCppMethod('wxDateTime*', 'FromTimeT', '(time_t timet)', 
         factory=True, isStatic=True,
-        doc="Construct a DateTime from a C time_t value, the number of seconds since the epoch.",
+        doc="Construct a :class:`DateTime` from a C ``time_t`` value, the number of seconds since the epoch.",
         body="return new wxDateTime(timet);")
                    
     c.addCppMethod('wxDateTime*', 'FromJDN', '(double jdn)', 
         factory=True, isStatic=True,
-        doc="Construct a DateTime from a Julian Day Number.\n\n"
+        doc="Construct a :class:`DateTime` from a Julian Day Number.\n\n"
             "By definition, the Julian Day Number, usually abbreviated as JDN, of a particular instant is the fractional number of days since 12 hours Universal Coordinated Time (Greenwich mean noon) on January 1 of the year -4712 in the Julian proleptic calendar.",
         body="return new wxDateTime(jdn);")
     
@@ -96,7 +96,7 @@ def run():
             unsigned short second=0, 
             unsigned short millisecond=0)""", 
         factory=True, isStatic=True,
-        doc="Construct a DateTime equal to Today() with the time set to the supplied parameters.",
+        doc="Construct a :class:`DateTime` equal to :meth:`Today` () with the time set to the supplied parameters.",
         body="return new wxDateTime(hour, minute, second, millisecond);")
 
     c.addCppMethod('wxDateTime*', 'FromDMY', 
@@ -108,7 +108,7 @@ def run():
             unsigned short second=0, 
             unsigned short millisecond=0)""", 
         factory=True, isStatic=True,
-        doc="Construct a DateTime using the supplied parameters.",
+        doc="Construct a :class:`DateTime` using the supplied parameters.",
         body="return new wxDateTime(day, month, year, hour, minute, second, millisecond);")
     
     # and give them some simple wrappers for Classic compatibility
@@ -355,7 +355,7 @@ def run():
     #---------------------------------------------
     # Convert to/from Python date objects
     module.addPyFunction('pydate2wxdate', '(date)', 
-        doc='Convert a Python date or datetime to a wx.DateTime object',
+        doc='Convert a Python date or datetime to a :class:`DateTime` object',
         body="""\
             import datetime
             assert isinstance(date, (datetime.datetime, datetime.date))
@@ -363,7 +363,7 @@ def run():
         """)
     
     module.addPyFunction('wxdate2pydate', '(date)', 
-        doc='Convert a wx.DateTime object to a Python datetime.',
+        doc='Convert a :class:`DateTime` object to a Python datetime.',
         body="""\
             import datetime
             assert isinstance(date, DateTime)

etgtools/sphinx_generator.py

@@ -1146,6 +1146,9 @@ class Image(Node):
             if key == 'name':
                 break
 
+        if 'appear-' in value:
+            return ''
+        
         image_path = os.path.normpath(os.path.join(DOXYROOT, 'images', value))
         static_path = os.path.join(OVERVIEW_IMAGES_ROOT, os.path.split(image_path)[1])
 
@@ -1727,7 +1730,13 @@ class Emphasis(Node):
            to avoid wrong ReST output.
         """
 
-        if self.element.tag == 'emphasis':
+
+        text = Node.Join(self, with_tail=False)
+
+        if '``' in text:
+            format = '%s'
+            emphasis = ''
+        elif self.element.tag == 'emphasis':
             format = '`%s`'
             emphasys = '`'
         elif self.element.tag == 'bold':
@@ -1736,8 +1745,6 @@ class Emphasis(Node):
 
         spacing = ('ParameterList' in self.GetHierarchy() and [' '] or [''])[0]
 
-        text = Node.Join(self, with_tail=False)
-
         if self.children:
 
             startPos = 0
@@ -1765,7 +1772,7 @@ class Emphasis(Node):
             text = newText
             
         else:
-            
+
             if text.strip():
                 text = spacing + format % text.strip()
 
@@ -2402,6 +2409,7 @@ class XMLDocString(object):
 
                 if found:
                     line = line.replace('wx.EmptyString', '""')
+                    line = line.replace('wx.', '')
                     newlines = self.CodeIndent(line, newlines)
 
         newdocs = ''
@@ -2477,6 +2485,7 @@ class XMLDocString(object):
             if self.is_overload:
                 arguments = '`%s`'%arguments.strip()
 
+        arguments = arguments.replace('wx.', '')
         self.arguments = arguments
 
 
@@ -3216,12 +3225,20 @@ class SphinxGenerator(generators.DocsGeneratorBase):
 
         if self.IsFullyDeprecated(pm):
             return
-        
+
         stream = StringIO()
         stream.write('\n   .. method:: %s%s\n\n' % (pm.name, pm.argsString))
-
+        
-##        docstrings = ConvertToPython(pm.pyDocstring).replace('\n', ' ')
+        docstrings = return_type = ''
-        docstrings = ConvertToPython(pm.pyDocstring)
+        
+        for line in pm.pyDocstring.splitlines():
+            if '->' in line:
+                arguments, after = line.strip().split("->")
+                return_type = self.ReturnSection(after)
+            else:
+                docstrings += line
+                
+        docstrings = ConvertToPython(docstrings)
 
         newdocs = ''
         spacer = ' '*6
@@ -3234,6 +3251,10 @@ class SphinxGenerator(generators.DocsGeneratorBase):
                 
         stream.write(newdocs + '\n\n')
 
+        if hasattr(pm, 'deprecated') and pm.deprecated:
+            text = '%s %s\n%s%s\n\n'%('      .. deprecated::', VERSION, ' '*9, pm.deprecated.replace('\n', ' '))
+            stream.write(text)
+
         name = RemoveWxPrefix(self.current_class.name) or self.current_class.pyName
         filename = self.current_module + "%s.txt"%name
 
@@ -3387,6 +3408,55 @@ class SphinxGenerator(generators.DocsGeneratorBase):
 
         return method_name, simple_docs
 
+    # ---------------------------------------------------------------------------
+    def ReturnSection(self, after):
+
+        if '(' in after:
+
+            rtype1 = ReturnType('`tuple`', None)
+            
+            return_section = after.strip().lstrip('(').rstrip(')')
+            return_section = return_section.split(',')
+            new_section = []
+            
+            for ret in return_section:
+                stripped = ret.strip()
+                if stripped in NO_MODULE:
+                    ret = NO_MODULE[stripped] + stripped
+                    new_section.append(':ref:`%s`'%ret)
+                else:
+                    if ret[0].isupper():
+                        new_section.append(':ref:`%s`'%stripped)
+                    else:
+                        new_section.append('`%s`'%stripped)
+
+            element = et.Element('return', kind='return')
+            element.text = '( %s )'%(', '.join(new_section))
+            
+            rtype2 = Section(element, None, 'method')
+            rtype = rtype1.Join() + rtype2.Join()
+            
+        else:
+
+            rtype = PythonizeType(after)
+
+            if not rtype:
+                return ''
+            
+            if rtype[0].isupper() or '.' in rtype:
+                rtype = ':ref:`%s`'%rtype
+            else:
+                rtype = '`%s`'%rtype
+
+            rtype = ReturnType(rtype, None)
+            rtype = rtype.Join()
+            
+        out = ''
+        for r in rtype.splitlines():
+            out += 6*' ' + r + '\n'
+            
+        return out
+
         
 # ---------------------------------------------------------------------------
 # helpers

sphinxtools/postprocess.py

@@ -54,7 +54,10 @@ def MakeHeadings():
         rel_path_index = img.find('_static')
         rel_path = img[rel_path_index:]
 
-        width = ('overload' in name and [16] or [32])[0]
+        width = 32
+        if 'overload' in name or 'contributed' in name:
+            width = 16
+
         text += templates.TEMPLATE_HEADINGS % (name, os.path.normpath(rel_path), width)
 
     writeIfChanged(heading_file, text)    
@@ -658,7 +661,9 @@ def PostProcess(folder):
         text = text.replace('<p><img alt="overload"', '<br><p><img alt="overload"')
         text = text.replace('<strong>Overloaded Implementations</strong>', '<em><strong>Overloaded Implementations</strong></em>')
         text = text.replace('<strong>~~~</strong></p>', '<hr style="color:#0000FF;background-color:#0000FF;height:1px;border:none;width:50%;float:left" /></p><br>')
-        
+
+        text = text.replace('<p><img alt="contributed"', '<br><p><img alt="contributed"')
+
         for item in HTML_REPLACE:
             text = text.replace('<dl class="%s">'%item, '<br><hr />\n<dl class="%s">'%item)
 

sphinxtools/utilities.py

@@ -378,7 +378,8 @@ def ConvertToPython(text):
         newlines.append(newline)
 
     formatted = "\n".join(newlines)
-    formatted = formatted.replace('\\', '\\\\')        
+    formatted = formatted.replace('\\', '\\\\')
+
     return formatted
             
 
@@ -764,7 +765,7 @@ def FormatContributedSnippets(kind, contrib_snippets):
     if kind == 'class':
         text = TEMPLATE_CONTRIB
     else:
-        text = '\n' + spacer + '**Contributed Examples:**\n\n'
+        text = '\n' + spacer + '|contributed| **Contributed Examples:**\n\n'
     
     for indx, snippet in enumerate(contrib_snippets):
         fid = open(snippet, 'rt')