diff --git a/docs/sphinx/_downloads/TreeCtrl.OnCompareItems.1.py b/docs/sphinx/_downloads/TreeCtrl.OnCompareItems.1.py new file mode 100644 index 00000000..31d7fdba --- /dev/null +++ b/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()) diff --git a/docs/sphinx/_static/images/sphinxdocs/contributed.png b/docs/sphinx/_static/images/sphinxdocs/contributed.png new file mode 100644 index 00000000..7f629f23 Binary files /dev/null and b/docs/sphinx/_static/images/sphinxdocs/contributed.png differ diff --git a/docs/sphinx/_static/images/widgets/fullsize/wxgtk/dataview.dataviewtreectrl.png b/docs/sphinx/_static/images/widgets/fullsize/wxgtk/dataview.dataviewtreectrl.png new file mode 100644 index 00000000..fd60548f Binary files /dev/null and b/docs/sphinx/_static/images/widgets/fullsize/wxgtk/dataview.dataviewtreectrl.png differ diff --git a/docs/sphinx/_static/images/widgets/fullsize/wxmac/dataview.dataviewtreectrl.png b/docs/sphinx/_static/images/widgets/fullsize/wxmac/dataview.dataviewtreectrl.png new file mode 100644 index 00000000..e7ee467e Binary files /dev/null and b/docs/sphinx/_static/images/widgets/fullsize/wxmac/dataview.dataviewtreectrl.png differ diff --git a/docs/sphinx/_static/images/widgets/fullsize/wxmsw/dataview.dataviewtreectrl.png b/docs/sphinx/_static/images/widgets/fullsize/wxmsw/dataview.dataviewtreectrl.png new file mode 100644 index 00000000..9238bce1 Binary files /dev/null and b/docs/sphinx/_static/images/widgets/fullsize/wxmsw/dataview.dataviewtreectrl.png differ diff --git a/docs/sphinx/rest_substitutions/overviews/dialog_overview.rst b/docs/sphinx/rest_substitutions/overviews/dialog_overview.rst index 8d0ba897..d17a0ce9 100644 --- a/docs/sphinx/rest_substitutions/overviews/dialog_overview.rst +++ b/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. diff --git a/docs/sphinx/rest_substitutions/overviews/events_overview.rst b/docs/sphinx/rest_substitutions/overviews/events_overview.rst index c78dfd97..2c529a7f 100644 --- a/docs/sphinx/rest_substitutions/overviews/events_overview.rst +++ b/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. diff --git a/docs/sphinx/rest_substitutions/overviews/filesystem_overview.rst b/docs/sphinx/rest_substitutions/overviews/filesystem_overview.rst index b1486925..a8249ec9 100644 --- a/docs/sphinx/rest_substitutions/overviews/filesystem_overview.rst +++ b/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". -* **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". +* **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"``. +* **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 ` 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:`FilterFSHandler`: A handler for compression schemes such as gzip. URLs are in the form, e.g.: "document.ps.gz#gzip:". +* :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:`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. diff --git a/docs/sphinx/rest_substitutions/overviews/html_overview.rst b/docs/sphinx/rest_substitutions/overviews/html_overview.rst index cbdfaf2e..a8225f7a 100644 --- a/docs/sphinx/rest_substitutions/overviews/html_overview.rst +++ b/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). diff --git a/docs/sphinx/rest_substitutions/overviews/tipprovider_overview.rst b/docs/sphinx/rest_substitutions/overviews/tipprovider_overview.rst index 615a5bb9..3bafa170 100644 --- a/docs/sphinx/rest_substitutions/overviews/tipprovider_overview.rst +++ b/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. diff --git a/docs/sphinx/rest_substitutions/snippets/python/contrib/TreeCtrl.OnCompareItems.1.py b/docs/sphinx/rest_substitutions/snippets/python/contrib/TreeCtrl.OnCompareItems.1.py new file mode 100644 index 00000000..31d7fdba --- /dev/null +++ b/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()) diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/TimerEvent.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/TimerEvent.1.py index 03df445a..c97c80a2 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/TimerEvent.1.py +++ b/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') diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/VListBox.GetFirstSelected.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/VListBox.GetFirstSelected.1.py index 7282d2f3..369f7381 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/VListBox.GetFirstSelected.1.py +++ b/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) diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/Window.SetBackgroundStyle.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/Window.SetBackgroundStyle.1.py index b2373b03..c1b4f18d 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/Window.SetBackgroundStyle.1.py +++ b/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.PostCreate(pre) + self.Create(parent) diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.Draw.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.Draw.1.py index c339eb4b..2cc77edd 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.Draw.1.py +++ b/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) diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.DrawInvisible.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.DrawInvisible.1.py index e10bed08..e8035d96 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlCell.DrawInvisible.1.py +++ b/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) diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlHelpWindow.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlHelpWindow.1.py index 679712d3..756952b8 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlHelpWindow.1.py +++ b/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") diff --git a/docs/sphinx/rest_substitutions/tables/VScrolledWindow.1.rst b/docs/sphinx/rest_substitutions/tables/VScrolledWindow.1.rst index 3e54a563..06aa8565 100644 --- a/docs/sphinx/rest_substitutions/tables/VScrolledWindow.1.rst +++ b/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` diff --git a/etg/_core.py b/etg/_core.py index 7ee9b7ee..ac3c2ac0 100644 --- a/etg/_core.py +++ b/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();") diff --git a/etg/checklst.py b/etg/checklst.py index 6aa792e8..8009b689 100644 --- a/etg/checklst.py +++ b/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)', diff --git a/etg/ctrlsub.py b/etg/ctrlsub.py index 59b4fe30..8436c374 100644 --- a/etg/ctrlsub.py +++ b/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)") diff --git a/etg/dataview.py b/etg/dataview.py index 803f70e5..335fef86 100644 --- a/etg/dataview.py +++ b/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, - and use `ItemToObject` to fetch that Python object again later for a given - DataViewItem. + :meth:`ObjectToItem` to create a :class:`DataViewItem` using a Python object as its ID, + and use :meth:`ItemToObject` to fetch that Python object again later for a given + :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. """, diff --git a/etg/datectrl.py b/etg/datectrl.py index 74423c4c..779e292e 100644 --- a/etg/datectrl.py +++ b/etg/datectrl.py @@ -20,7 +20,7 @@ DOCSTRING = "" # this script. ITEMS = [ "wxDatePickerCtrl", ] - + #--------------------------------------------------------------------------- def run(): diff --git a/etg/event.py b/etg/event.py index da0c431c..52ed62f8 100644 --- a/etg/event.py +++ b/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. - Returns True if successful. + Disconnects the event handler binding for event from `self`. + Returns ``True`` if successful. """, body="""\ if source is not None: diff --git a/etg/listctrl.py b/etg/listctrl.py index 4cbb38ca..1715fdbc 100644 --- a/etg/listctrl.py +++ b/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): diff --git a/etg/menu.py b/etg/menu.py index 4ab79d4b..c20245a1 100644 --- a/etg/menu.py +++ b/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) diff --git a/etg/sizer.py b/etg/sizer.py index 5ee633e7..0ec8bf79 100644 --- a/etg/sizer.py +++ b/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);") diff --git a/etg/window.py b/etg/window.py index 83ae8b29..6b309efc 100644 --- a/etg/window.py +++ b/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="""\ diff --git a/etg/wxdatetime.py b/etg/wxdatetime.py index b4bed899..836796f8 100644 --- a/etg/wxdatetime.py +++ b/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) diff --git a/etgtools/sphinx_generator.py b/etgtools/sphinx_generator.py index bbfab19f..d5457061 100644 --- a/etgtools/sphinx_generator.py +++ b/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 = ConvertToPython(pm.pyDocstring) + + docstrings = return_type = '' + + 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 diff --git a/sphinxtools/postprocess.py b/sphinxtools/postprocess.py index cee3043d..46032d3b 100644 --- a/sphinxtools/postprocess.py +++ b/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('

overload

overloadOverloaded Implementations', 'Overloaded Implementations') text = text.replace('~~~

', '


') - + + text = text.replace('

contributed

contributed'%item, '

\n
'%item) diff --git a/sphinxtools/utilities.py b/sphinxtools/utilities.py index f7fd90ce..e58e878d 100644 --- a/sphinxtools/utilities.py +++ b/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')