From 604b778a2c4bf7fc6041d7e5f1632dac1774ea2b Mon Sep 17 00:00:00 2001 From: Andrea Gavana Date: Fri, 30 Nov 2012 20:54:13 +0000 Subject: [PATCH] Phoenix docs: handle funny-formatted heading sections for window styles, extra styles and event handling; Add missing modules in the `main.html` Sphinx file; Convert some more snippets, specifying the highlight language used (XML/HTML for some snippets in `wx.html`); Correctly reference classes and functions in `wx.Bitmap` pure-Python methods. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxPython/Phoenix/trunk@73069 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/sphinx/_templates/main.html | 21 ++++++----- .../Window.ConvertDialogToPixels.1.py | 8 ++-- .../converted/html.HtmlTag.GetBeginPos.1.py | 1 + .../converted/html.HtmlTag.GetEndPos1.1.py | 1 + .../converted/html.HtmlTag.GetEndPos2.1.py | 1 + etg/bitmap.py | 16 ++++---- etg/webview.py | 4 +- etgtools/sphinx_generator.py | 37 +++++++++++++------ sphinxtools/constants.py | 5 ++- sphinxtools/postprocess.py | 2 +- sphinxtools/utilities.py | 15 ++++++-- 11 files changed, 71 insertions(+), 40 deletions(-) diff --git a/docs/sphinx/_templates/main.html b/docs/sphinx/_templates/main.html index 02ede7f2..5db1efdb 100644 --- a/docs/sphinx/_templates/main.html +++ b/docs/sphinx/_templates/main.html @@ -4,17 +4,17 @@

Welcome to wxPython (Phoenix)'s documentation!

- Welcome! This is the documentation for wxPython {{ release }}, last updated |TODAY| from + Welcome! This is the documentation for wxPython {{ release }}, last updated |TODAY| from Subversion revision |SVN|.

Phoenix is the code name for the new version of wxPython. Robin Dunn called - this Project Phoenix because in the + this Project Phoenix because in the process of doing this project wxPython's implementation will be utterly destroyed and then - reborn in a new and marvelous way, much like the mythical Phoenix rising from the ashes - of its former self. For wxPython many things about how the wrapper/bindings code is - produced will be changing, and we'll also be eliminating some other crud along the way. + reborn in a new and marvelous way, much like the mythical Phoenix rising from the ashes + of its former self. For wxPython many things about how the wrapper/bindings code is + produced will be changing, and we'll also be eliminating some other crud along the way.

@@ -27,8 +27,8 @@

  • Migration Guide: the Migration Guide will give you some hints on how to modify your existing wxPython applications to be compatible with Phoenix, - and the Classic vs. Phoenix document will give details - on the identifier names that have changed and what you should use instead in your applications. + and the Classic vs. Phoenix document will give details + on the identifier names that have changed and what you should use instead in your applications. These documents are updated as the project progresses, so be sure to check them often.
    • @@ -52,10 +52,10 @@

    wx Core Classes
    The classes which appear in the wx namespace

    - +

    wx Core Functions
    Standalone functions

    - +

    wx.adv
    Less commonly used or more advanced classes

    @@ -68,6 +68,9 @@

    wx.html
    Widget and supporting classes for a generic html renderer

    +

    wx.html2
    + Widget and supporting classes to render web (HTML / CSS / javascript) documents

    +

    wx.lib
    diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/Window.ConvertDialogToPixels.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/Window.ConvertDialogToPixels.1.py index a7b39080..3be6157b 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/Window.ConvertDialogToPixels.1.py +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/Window.ConvertDialogToPixels.1.py @@ -1,5 +1,5 @@ -# The C++ convenience macro does not apply for Python, however you can -# accomplish something similar with a function like this -def DLG_UNIT(parent, point): - return parent.ConvertDialogToPixels(point) + # The C++ convenience macro does not apply for Python, however you can + # accomplish something similar with a function like this + def DLG_UNIT(parent, point): + return parent.ConvertDialogToPixels(point) diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetBeginPos.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetBeginPos.1.py index 63224f09..bd71dee9 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetBeginPos.1.py +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetBeginPos.1.py @@ -1,3 +1,4 @@ # .. code-block:: text bla bla bla bla bla internal text bla bla + | \ No newline at end of file diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos1.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos1.1.py index 0d8beacb..392d08fe 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos1.1.py +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos1.1.py @@ -1,3 +1,4 @@ # .. code-block:: text bla bla bla bla bla internal text bla bla + | \ No newline at end of file diff --git a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos2.1.py b/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos2.1.py index 0d8beacb..760698a2 100644 --- a/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos2.1.py +++ b/docs/sphinx/rest_substitutions/snippets/python/converted/html.HtmlTag.GetEndPos2.1.py @@ -1,3 +1,4 @@ # .. code-block:: text bla bla bla bla bla internal text bla bla + | \ No newline at end of file diff --git a/etg/bitmap.py b/etg/bitmap.py index 05f0a76c..f8400ad4 100644 --- a/etg/bitmap.py +++ b/etg/bitmap.py @@ -174,7 +174,7 @@ def run(): c.addCppMethod('void', 'CopyToBuffer', '(wxPyBuffer* data, wxBitmapBufferFormat format=wxBitmapBufferFormat_RGB, int stride=-1)', doc="""\ - Copy pixel data to a buffer object. See `CopyFromBuffer` for buffer + Copy pixel data to a buffer object. See :meth:`CopyFromBuffer` for buffer format details.""", body="""\ wxPyCopyBitmapToBuffer(self, (byte*)data->m_ptr, data->m_len, format, stride); @@ -188,7 +188,7 @@ def run(): isStatic=True, factory=True, doc="""\ - Creates a `wx.Bitmap` from in-memory data. The data and alpha + Creates a :class:`Bitmap` from in-memory data. The data and alpha parameters must be a Python object that implements the buffer interface, such as a string, bytearray, etc. The data object is expected to contain a series of RGB bytes and be at least @@ -198,7 +198,7 @@ def run(): 'premultiplied' by the alpha values. (The other platforms do the multiplication themselves.) - Unlike `wx.ImageFromBuffer` the bitmap created with this function + Unlike :func:`ImageFromBuffer` the bitmap created with this function does not share the memory block with the buffer object. This is because the native pixel buffer format varies on different platforms, and so instead an efficient as possible copy of the @@ -240,12 +240,12 @@ def run(): isStatic=True, factory=True, doc="""\ - Creates a `wx.Bitmap` from in-memory data. The data parameter + Creates a :class:`Bitmap` from in-memory data. The data parameter must be a Python object that implements the buffer interface, such as a string, bytearray, etc. The data object is expected to contain a series of RGB bytes and be at least width*height*3 bytes long. - Unlike `wx.ImageFromBuffer` the bitmap created with this function + Unlike :func:`ImageFromBuffer` the bitmap created with this function does not share the memory block with the buffer object. This is because the native pixel buffer format varies on different platforms, and so instead an efficient as possible copy of the @@ -280,14 +280,14 @@ def run(): isStatic=True, factory=True, doc="""\ - Creates a `wx.Bitmap` from in-memory data. The data parameter + Creates a :class:`Bitmap` from in-memory data. The data parameter must be a Python object that implements the buffer interface, such as a string, bytearray, etc. The data object is expected to contain a series of RGBA bytes and be at least width*height*4 bytes long. On Windows and Mac the RGB values will be 'premultiplied' by the alpha values. (The other platforms do the multiplication themselves.) - Unlike `wx.ImageFromBuffer` the bitmap created with this function + Unlike :func:`ImageFromBuffer` the bitmap created with this function does not share the memory block with the buffer object. This is because the native pixel buffer format varies on different platforms, and so instead an efficient as possible copy of the @@ -318,7 +318,7 @@ def run(): isStatic=True, factory=True, doc="""\ - Creates a new empty 32-bit `wx.Bitmap` where every pixel has been + Creates a new empty 32-bit :class:`Bitmap` where every pixel has been initialized with the given RGBA values. """, body="""\ diff --git a/etg/webview.py b/etg/webview.py index bb631cab..21457fd8 100644 --- a/etg/webview.py +++ b/etg/webview.py @@ -18,7 +18,7 @@ DOCSTRING = "" # The classes and/or the basename of the Doxygen XML files to be processed by # this script. ITEMS = [ 'wxWebViewHistoryItem', - 'wxWebViewHandler', + 'wxWebViewHandler', 'wxWebViewArchiveHandler', 'wxWebViewFSHandler', 'wxWebView', @@ -67,7 +67,7 @@ def run(): wxVector > vector = self->{method}(); for (size_t idx=0; idx < vector.size(); idx++) {{ PyObject* obj; - wxWebViewHistoryItem* item = new wxWebViewHistoryItem(*vector[idx].get()); + wxWebViewHistoryItem* item = new wxWebViewHistoryItem(*vector[idx].get()) obj = wxPyConstructObject((void*)item, "wxWebViewHistoryItem", true); PyList_Append(result, obj); Py_DECREF(obj); diff --git a/etgtools/sphinx_generator.py b/etgtools/sphinx_generator.py index 96cf6705..c3dcebc4 100644 --- a/etgtools/sphinx_generator.py +++ b/etgtools/sphinx_generator.py @@ -1431,8 +1431,9 @@ class Snippet(Node): if highlight: docstrings += '\n\n%s\n\n'%highlight + else: + docstrings += '::\n\n' - docstrings += '::\n\n' docstrings += code.rstrip() + '\n\n' if self.element.tail and len(self.element.tail.strip()) > 1: @@ -2676,7 +2677,7 @@ class XMLDocString(object): # ----------------------------------------------------------------------- - def EventsInStyle(self, line, class_name, added=False): + def EventsInStyle(self, line, class_name, added): docstrings = '' newline = line @@ -2688,19 +2689,28 @@ class XMLDocString(object): docstrings += templates.TEMPLATE_WINDOW_STYLES % class_name elif 'The following event handler macros' in line and not added: - last = line.index(':') - line = line[last+1:].strip() + index = line.index('The following event handler macros') + newline1 = line[0:index] + '\n\n' + macro_line = line[index:] + last = macro_line.index(':') + line = macro_line[last+1:].strip() if line.count(':') > 2: newline = 'Handlers bound for the following event types will receive one of the %s parameters.'%line else: newline = 'Handlers bound for the following event types will receive a %s parameter.'%line - docstrings += templates.TEMPLATE_EVENTS % class_name + docstrings += newline1 + templates.TEMPLATE_EVENTS % class_name + docstrings = docstrings.replace('Event macros for events emitted by this class: ', '') + newline = newline.replace('Event macros for events emitted by this class: ', '') added = True - elif 'Event macros for events' in line and not added: - docstrings += templates.TEMPLATE_EVENTS % class_name + elif 'Event macros for events' in line: + if added: + newline = '' + else: + docstrings += templates.TEMPLATE_EVENTS % class_name + added = True elif 'following extra styles:' in line: @@ -2740,9 +2750,10 @@ class XMLDocString(object): added = False for line in item.splitlines(): if line.strip(): - newdocs, newline, added = self.EventsInStyle(line, class_name, added) - docstrings += newdocs - docstrings += spacer + newline + '\n' + newdocs, newline, added = self.EventsInStyle(line, class_name, added) + if newline.strip(): + docstrings += newdocs + docstrings += spacer + newline + '\n' else: docstrings += line + '\n' @@ -2801,7 +2812,11 @@ class XMLDocString(object): docstrings += spacer + line + '\n' docstrings += '%s**~~~**\n\n'%spacer - + + if '**Perl Note:**' in docstrings: + index = docstrings.index('**Perl Note:**') + docstrings = docstrings[0:index] + stream.write(docstrings + "\n\n") diff --git a/sphinxtools/constants.py b/sphinxtools/constants.py index 62f522b2..eae32cb3 100644 --- a/sphinxtools/constants.py +++ b/sphinxtools/constants.py @@ -24,7 +24,8 @@ from buildtools.config import phoenixDir, wxDir IGNORE = ['wxPython', 'wxWidgets', 'wxOSX', 'wxMGL', 'wxDFB', 'wxMAC', 'wxGTK', 'wxGTK2', 'wxUniversal', 'OS', 'X', 'OSX', 'DFB', 'MAC', 'GTK', 'GTK2', 'MSW', 'wxMSW', 'X11', 'OS2', 'MS', 'XP', 'GTK+', 'UI', 'GUI', '--', 'OTOH', 'GDI+', 'API', 'NT', 'RTL', 'GDI', '3D', 'MDI', 'SDI', 'TDI', 'URL', - 'XPM', 'HTML', 'MIME', 'C++', 'XDG', 'A4', 'A5', 'KDE', 'GNOME', 'XFCE'] + 'XPM', 'HTML', 'MIME', 'C++', 'XDG', 'A4', 'A5', 'KDE', 'GNOME', 'XFCE', 'CSS', 'IE', 'FONT', + 'SIZE', 'COLOR'] # C++ stuff to Python/ReST stuff VALUE_MAP = {'true': '``True``', @@ -176,7 +177,7 @@ SECTIONS_EXCLUDE = { 'Menu' : ('|phoenix_title| Allocation strategy', '|phoenix_title| Event handling'), 'MouseState' : ('This class is implemented', '.. seealso::'), 'Panel' : ('Please see :ref:`/', 'if not all characters'), - 'TextCtrl' : ('|phoenix_title| TextCtrl and ``C++`` Streams', '|phoenix_title| Event Handling'), + 'TextCtrl' : ('|phoenix_title| TextCtrl and C++ Streams', '|phoenix_title| Event Handling'), 'TextEntry' : ('Notice that you need', 'Currently this method is only '), } diff --git a/sphinxtools/postprocess.py b/sphinxtools/postprocess.py index a094e329..bf4f123d 100644 --- a/sphinxtools/postprocess.py +++ b/sphinxtools/postprocess.py @@ -170,7 +170,7 @@ def BuildEnumsAndMethods(sphinxDir): # Replace ArrayXXX stuff... - for cpp in ['ArrayString()', 'ArrayInt()', 'ArrayDouble()']: + for cpp in ['ArrayString()', 'ArrayInt()', 'ArrayDouble()', 'ArrayString']: text = text.replace(cpp, '[]') text = TooltipsOnInheritance(text, class_summary) diff --git a/sphinxtools/utilities.py b/sphinxtools/utilities.py index af27f1b9..5d67b38b 100644 --- a/sphinxtools/utilities.py +++ b/sphinxtools/utilities.py @@ -214,9 +214,14 @@ def ReplaceCppItems(line): item = 'float' if len(item.replace('``', '')) > 2: - # Avoid replacing standalone '&&' and similar - for cpp in CPP_ITEMS[0:2]: - item = item.replace(cpp, '') + if '*' in item: + try: + eval(item) + item = item.replace('*', 'x') + except: + # Avoid replacing standalone '&&' and similar + for cpp in CPP_ITEMS[0:2]: + item = item.replace(cpp, '') newstr.append(item) @@ -282,6 +287,9 @@ def PythonizeType(ptype): if 'Image.' in ptype: ptype = ptype.split('.')[-1] + + if ptype.endswith('&'): + ptype = ':class:`%s`'%ptype[0:-1] return ptype @@ -354,6 +362,7 @@ def ConvertToPython(text): if '``' not in newword and '()' not in word and '**' not in word: word = word.replace(newword, "``%s``"%newword) + word = word.replace('->', '.') newline.append(word) newline = spacer + ''.join(newline)