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()
+
+