wxpython documentation

wxPython Users
1

Re: " wxpython
documentation" @ http://groups.google.com/group/wxpython-users/browse_thread/thread/4a75056eacd8c579
on 2010-08-12

Fidel,
You certainly are not alone getting endlessly frustrated trying to

find some the most basic information about using particular wx
methods. *** There is no free complete and single source for
wx documentation***.

Here are some readily available partial documentation and working

example sources (listed in no particular order):

1 - [http://www.wxpython.org/docs/api/](http://www.wxpython.org/docs/api/)

You can browse this site directly, but I prefer to use Google to do
a general search like you did because Google always lists this site
in the first or second listed hit. The most effective Google search
phrase template (for me) is:

    wxpython "wx.choice"

Use the quotes as shown. Just replace the word [ choice ] with the

wx control_name or wx constant_name of your choosing. The [ wx. ]
part is very necessary to search for all relevant web pages…

2 - The "wxPython Docs Demos and Tools". These are 2 separate

downloads and installations from the wxPython package. There are
very many working examples in the single all-inclusive demo program.
Every “built-in” and many “pure wxPython” controls have working
demos. However, detailed method explanations are very few and far
between. The example code is very easily viewed and copied. Getting
any one control demo sample to run as a stand-alone app is a real
PITA. The wxPython demo program and the HTML doc packages are
available in the same web page as the wxPython download: wxPython2 Docs Demos
and Tools

3 - The [      WxWidgets C++

documentation](http://www.wxwidgets.org/docs/) . Most of this has been already regenerated into
wxPython documentation, but there are sometimes extra usable
information here.

4 - Searching all the [ .py ] files for the usage of the control in

which you are interested. On Win7 (and Vista ?) platforms,
Microsoft, in their infinite wisdom, has eliminated the Windows XP
text string search capability in the Windows Explorer file search
utility. However, I found a truly great 3rd part search utility over
11 years ago that was developed in the NT days and still works as
extremely efficiently as it originally did. I have researched
literally 100 other search/search+replace apps and they all have
serious, if not fatal, deficiencies that make them completely
useless. My life-saving utility is called Search &
Replace by Funduc Software. It has been updated for Vista and
Win7 but it appears and operates identically to the original
release.

    If you are reasonably proficient using regular expressions (I'm

not) you can perform complex searches and search+replaces using
egrep regex phrase searches instead of the default plain text
searches. This program is literally “worth its weight in gold” to me
and is extraordinarily fast. (No, I don’t get any “cut” from its
sales. It costs only USD $25) It’s offered in 32-bit and 64-bit
versions for MSW, but I’ve never encountered any working 32-bit MSW
program that didn’t work on a MSW 64-bit platform. 32-bit MSW
programs run properly on each of the 2 MSW platforms for XP, Vista
and Win7.

5 - Organize you own collection of Python and wxPython sample apps

then use Search&Replace to locate sample usages of the control
or parameter you are researching. I’ve been collecting working
samples and adding explanation comments for years and this source is
extremely useful to me. This takes lots of time and effort, but this
is well worth it to me. I also “play around” with them by
temporarily altering the code to see the differences.

6 - [      ActiveState.com Code

Recipes](http://code.activestate.com/recipes/) . Lots of useful wxPython and Python working examples
are free-for-the-taking. ActiveState wxPython and Python are
commercial packages that are NOT open source. However, it seems to
have all the standard Python interpreters and many add-on packages
for all the wxPython and Python versions. I guess that their
customers buy them mostly for their documentation. I wouldn’t know.
I use these 8 methods to figure out what I need to know. You can
always ask
right here if you get really stuck or want to know
something obscure (or just not documented).

7 - [www.daniweb.com](www.daniweb.com) - There's lots of

good working examples here.

8 - [      Right

Here !](http://groups.google.com/group/wxpython-users/) I first do all my own research
homework. Whatever useful info turns up I file into my accumulated
research, item 5, because I do not have a photographic memory.

Other Things That You Should Be Aware (or "Beware" ?!):

- Finding parameter names and parameter constant values and their

documentation is unnecessarily difficult. You can sometimes find
them listed in the actual wxPython code implementation buried within
your Python/wxPython …/site-packages/… folder.

- Over half my library of sample apps have NOT come from the

wxPython-users discussion board or the wxPython.org sites. They have
been posted from many other discussion boards. These sites are
mostly *nix platform developers’ discussion forums. I’m amazed that
the vast majority of the apps work properly on Windows platforms.
They will show up on Google searches.

Happy Hunting  (I mean this literally)

Ray Pasco
2

thanks!!..

these are all very good tips!, thanks for the help..

the one you miss was the one that steve told in a couple of mail

back, about using the “dir” function to search all the methods of a
wxpython specific widget!..

I found that one very good..

thanks again for the tips! and the help!..
···

wxPython-users+unsubscribe@googlegroups.com
http://groups.google.com/group/wxPython-users?hl=en

3

Here are some readily available partial documentation and working example
sources (listed in no particular order):

There's also Andrea's:

http://xoomer.virgilio.it/infinity77/wxPython/APIMain.html

4

Oops, C M, I missed this major doc source. It's very well organized
and very easy to use. Still, wx constants such as
wx.DEFAULT_FRAME_STYLE, etc., etc., have no documentation source that
I've come across, and there sure are a lot of them. Just what style
flags define wx.DEFAULT_FRAME_STYLE ??? (The answer to this one is too
easy. Most wx constants are not defined in any docs.)

I'm sure there are plenty of other people's suggestions for
documentation sources.

Why can't all these be posted as a "sticky note" on the main page so
everyone can see them ?

Ray

···

On Aug 13, 8:06 pm, C M <cmpyt...@gmail.com> wrote:

> Here are some readily available partial documentation and working example
> sources (listed in no particular order):

There's also Andrea's:

http://xoomer.virgilio.it/infinity77/wxPython/APIMain.html

5

Oops, C M, I missed this major doc source. It's very well organized
and very easy to use. Still, wx constants such as
wx.DEFAULT_FRAME_STYLE, etc., etc., have no documentation source that
I've come across,

Unless I misunderstand you, aren't they in the wxWidgets docs (and
therefore Andrea's)?
For wx.DEFAULT_FRAME_STYLE, if you go to the wxWidgets docs, here:

http://docs.wxwidgets.org/2.6/wx_wxframe.html

And look under Window styles, it's there.

In Andrea's, here:
http://xoomer.virgilio.it/infinity77/wxPython/Widgets/wx.Frame.html

Also under Window styles. I've found those parts of the docs crucial
to knowing what I'm doing when tweaking things.

and there sure are a lot of them. Just what style
flags define wx.DEFAULT_FRAME_STYLE ??? (The answer to this one is too
easy. Most wx constants are not defined in any docs.)

From that page:
"Defined as wx.MINIMIZE_BOX | wx.MAXIMIZE_BOX | wx.RESIZE_BORDER |
wx.SYSTEM_MENU | wx.CAPTION | wx.CLOSE_BOX | wx.CLIP_CHILDREN."

Che

···

On Sat, Aug 14, 2010 at 3:26 PM, WinCrazy <pascor@verizon.net> wrote:

6

Something not as apparent (but well worth a read) are Andrea’s AGW specific pages:

http://xoomer.virgilio.it/infinity77/AGW_Docs/index.html

7

...

There's also Andrea's:
http://xoomer.virgilio.it/infinity77/wxPython/APIMain.html

At the end of 2008 this started a discussion about the wxPython documentation, my reading of the conclusion to that thread was.

- base the wxPython docs on the wxWidgets 2.9 docs
- some initial manual work is needed to generate out of the wxWidgets docs and the wxPython docs (wx.lib etc) the new docs

I don't want to stir things, but would be interested to know where this all stands.

Could people like myself help in whatever manual work is involved?

Werner

P.S.
Hopefully the wxPython docs will be Sphinx based, which can easily produce the .cmh, a .pdf and .html versions of the docs.

···

On 14/08/2010 02:06, C M wrote:

8

HI Werner,

...

There's also Andrea's:
http://xoomer.virgilio.it/infinity77/wxPython/APIMain.html

At the end of 2008 this started a discussion about the wxPython
documentation, my reading of the conclusion to that thread was.

- base the wxPython docs on the wxWidgets 2.9 docs
- some initial manual work is needed to generate out of the wxWidgets docs
and the wxPython docs (wx.lib etc) the new docs

I don't want to stir things, but would be interested to know where this all
stands.

Your reading is correct: at that time, there was quite a debate about
the docs I produced with Sphinx. The docs generated by Sphinx are
without doubts nicer than the Doxygen-based ones, but a fair point
raised by Kevin, Robin and others was that, with the current way the
docs are handled in SWIG/wxWidgets, too much manual work would be
needed.

However, in order to switch from this state to an easier-to-handle
situation, only one thing would be needed: instruct SWIG to output the
wxPython-friendly help strings inside every method docstring. I.e.,
instead of having:

    def __init__(self, *args, **kwargs):
        """
        __init__(self, EventType commandType=wxEVT_NULL, int winid=0,
int pos=0,
            int orient=0) -> ScrollEvent
        """
        _core_.ScrollEvent_swiginit(self,_core_.new_ScrollEvent(*args,
**kwargs))

You would have:

    def __init__(self, *args, **kwargs):
        """
        Class constructor.

        :param `commandType`: eventtype
        :param `winid`: int
        :param `pos`: int
        :param `orient`: int

        :return: `wx.ScrollEvent`.
       """

Or something along these lines. Obviously, in this case the parameter
descriptions are not very helpful (they only mention "int"), but if
the description is present in the wxWidgets docs, it would be nice to
have a way to extract them and put them inside the method docstring.
In short, if we can output as much as possible help strings and
documentation strings inside method/class/module docstrings, then the
whole process of generating the documentation with Sphinx can be
automated like a breeze, up to the generation of html, pdf and chm
files.

Could people like myself help in whatever manual work is involved?

Of course you can: your knowledge of wxPython and of the various
intricacies of the library are extremely useful in analyzing the
slight differences between the wxWidgets docs (C++) and the wxPython
ones, in spotting errors in the automatically generated docs, and in
general provide ideas (and code) on how to best handle the conversion
between C++ docs and Python ones.

However, until Robin has given his final word, I don't think it's wise
to start something just yet... I remember I was bitten quite hard by
people's reactions on the wxPython docs I generated back in 2008...

Andrea.

"Imagination Is The Only Weapon In The War Against Reality."
http://xoomer.alice.it/infinity77/

==> Never *EVER* use RemovalGroup for your house removal. You'll
regret it forever.
The Doomed City: Removal Group: the nightmare <==

···

On 15 August 2010 11:50, werner wrote:

On 14/08/2010 02:06, C M wrote:

9

Yes, this is another rich source of info. This should be "wx
documentation source #11 (listed in no particular order)".

All the info there is good, but many crucial explanations are missing.
For one small example, under wx.Boxsizer flags, they are all listed,
but the critical fact that they apply only to the opposite axis to
which the BoxSizer was created is missing. This is critical to know to
be able to understand how the BoxSizer works, yet this little tidbit
is just not there. This, most certainly, wasn't done intentionally,
but no one has bothered to properly review this in all the years it
has been posted there.

You might think this is a trivial example, which it might very well
be, but there are 10,000 other missing critical explanations in the
docs, too. I realize the WxWidgets, Python and wxPython developers
don't get paid for any of their work, but it's obvious that the docs
were not reviewed by "newbies" with a "fresh" view who would be much
more aware of what all the other important info and, especially,
explanations that are missing in the docs.

Ray

···

On Aug 14, 10:28 pm, C M <cmpyt...@gmail.com> wrote:

On Sat, Aug 14, 2010 at 3:26 PM, WinCrazy <pas...@verizon.net> wrote:
> Oops, C M, I missed this major doc source. It's very well organized
> and very easy to use. Still, wx constants such as
> wx.DEFAULT_FRAME_STYLE, etc., etc., have no documentation source that
> I've come across,

Unless I misunderstand you, aren't they in the wxWidgets docs (and
therefore Andrea's)?
For wx.DEFAULT_FRAME_STYLE, if you go to the wxWidgets docs, here:

wxFrame

And look under Window styles, it's there.

In Andrea's, here:http://xoomer.virgilio.it/infinity77/wxPython/Widgets/wx.Frame.html

Also under Window styles. I've found those parts of the docs crucial
to knowing what I'm doing when tweaking things.

> and there sure are a lot of them. Just what style
> flags define wx.DEFAULT_FRAME_STYLE ??? (The answer to this one is too
> easy. Most wx constants are not defined in any docs.)

From that page:
"Defined as wx.MINIMIZE_BOX | wx.MAXIMIZE_BOX | wx.RESIZE_BORDER |
wx.SYSTEM_MENU | wx.CAPTION | wx.CLOSE_BOX | wx.CLIP_CHILDREN."

Che