[wxPython] wxPython Documentation

wxPython Users
1

Hi guys,

LIke most new users of wxPython, I guess I'm suffering a bit from documentation
withdrawal -- the only wxPython docs I've been able to find is the modified
version of the wxWindows reference, with Robin's comments added where wxPython
differs from wxWindows itself. Apart from that, all I've found is the (alas,
brief and incomplete) tutorial on the wxPython web site, the notes included
in the official wxPython docs, and of course the demo -- which is an absolute
God-send so long as it covers the things you're trying to learn about, but as
soon as you try to go beyond the specific examples it covers, you end up doing
an awful lot of guessing...

Are there any other docs which I've missed out on, or is that it? Now, please
don't get me wrong: I'm not criticising...far from it! Robin has much better
things to do with his time than write detailed documentation and tutorials for
new users, and his approach of taking the wxWindows docs and adding notes
relevant to wxPython is an excellent trade-off, and combined with the demo is a
pretty good way of getting started -- as far as it goes.

It seems to me, though, that the main thing that wxPython is lacking is a
detailed set of documentation. wxPython itself is an absolutely awesome GUI
toolkit, and combined with Python it's by far the best GUI development
enviroment I've seen in over twelve years of writing big, GUI-intensive
systems. It does, however, seem to be shackled by the lack of in-depth
documentation. If the documentation was as good as wxPython itself (including,
say, a detailed user's guide, a Python-specific reference, extended tutorials
and a cookbook of solutions), new users would have a much easier time, and I'm
sure wxPython would become much more popular as a result.

I see from the mailing list archives that various people have raised this
bugaboo in the past, but nothing seems to have come of it. If there really
isn't anyone working on extending the wxPython docs, I'd be keen to tackle it
myself -- I've written quite a few tutorials and reference manuals in the past, so I'm
not exactly a neophyte in this regard...and since I don't know C++ this is
probably the best contribution I could make to the wxPython project.

Now, I'm obviously still learning wxPython myself, but I've been collecting
notes about how the various parts of wxPython work, and in particular the
things which would be confusing to a novice. If it'd be worthwhile, I'd be
happy to keep writing notes over the next few months as I learn, and then put
it all together into a new-user tutorial. A detailed user's guide, a cookbook
of common UI tasks and how to achieve them, and maybe even a Python-specific
reference, might all be possible after that...

Thoughts?

Cheers,

- Erik.

2

If the documentation was as good as wxPython itself (including,
say, a detailed user's guide, a Python-specific reference, extended

tutorials

and a cookbook of solutions),

You've read my mind. This is almost the same as the outline of the book I'm
writing! (And before you ask, it's in the eary stages still and no, there's
nothing to look at yet. :wink:

new users would have a much easier time, and I'm
sure wxPython would become much more popular as a result.

I agree.

Now, I'm obviously still learning wxPython myself, but I've been

collecting

notes about how the various parts of wxPython work, and in particular the
things which would be confusing to a novice. If it'd be worthwhile, I'd

be

happy to keep writing notes over the next few months as I learn, and then

put

it all together into a new-user tutorial.

I think it would be very worthwile, but why wait a few months? If each
thing could be made into a standalone mini how-to then they could be put on
the website as you do them and people could start benefiting right away. It
may even inspire other people to start doing it too.

There is also the possibility, as Lucas Bruand is doing, of doing a more
formal Python How-To to become part of the collection at
http://py-howto.sourceforge.net/. You can see some conversation about it as
it progresses on the new wxPython-docs mail list at
http://lists.wxwindows.org/mailman/listinfo/wxpython-docs

myself -- I've written quite a few tutorials and reference manuals in the

past, so I'm

not exactly a neophyte in this regard...and since I don't know C++ this is
probably the best contribution I could make to the wxPython project.

Perhaps a good topic to start with, since you've obviously figured out how
to use the C++ docs is little guide for using the C++ docs by someone who
doesn't know C++. (While the pain is still fresh in your memory :wink:

Let me know what you think about these ideas. I've been planning on putting
a Wiki (a MoinMoin actually) on the wxPython website. User contributed mini
how-to's and FAQ answers are probably a great thing to get it started with.

···

--
Robin Dunn
Software Craftsman
robin@AllDunn.com Java give you jitters?
http://wxPython.org Relax with wxPython!

3

I think it would be a good thing to have a standard format for wxPython
documentation. Even if everyone don't stick to it... If anyone is interested
in adding things in the Howto, you are welcome...

        Bye,

PS Rob, Thanks for rewriting the example program on forms...

···

----- Original Message -----
From: "Robin Dunn" <robin@alldunn.com>
To: <wxpython-users@lists.wxwindows.org>
Sent: Tuesday, April 03, 2001 9:15 AM
Subject: Re: [wxPython] wxPython Documentation

> If the documentation was as good as wxPython itself (including,
> say, a detailed user's guide, a Python-specific reference, extended
tutorials
> and a cookbook of solutions),

You've read my mind. This is almost the same as the outline of the book

I'm

writing! (And before you ask, it's in the eary stages still and no,

there's

nothing to look at yet. :wink:

> new users would have a much easier time, and I'm
> sure wxPython would become much more popular as a result.

I agree.

> Now, I'm obviously still learning wxPython myself, but I've been
collecting
> notes about how the various parts of wxPython work, and in particular

the

> things which would be confusing to a novice. If it'd be worthwhile, I'd
be
> happy to keep writing notes over the next few months as I learn, and

then

put
> it all together into a new-user tutorial.

I think it would be very worthwile, but why wait a few months? If each
thing could be made into a standalone mini how-to then they could be put

on

the website as you do them and people could start benefiting right away.

It

may even inspire other people to start doing it too.

There is also the possibility, as Lucas Bruand is doing, of doing a more
formal Python How-To to become part of the collection at
http://py-howto.sourceforge.net/. You can see some conversation about it

as

it progresses on the new wxPython-docs mail list at
http://lists.wxwindows.org/mailman/listinfo/wxpython-docs

> myself -- I've written quite a few tutorials and reference manuals in

the

past, so I'm
> not exactly a neophyte in this regard...and since I don't know C++ this

is

> probably the best contribution I could make to the wxPython project.

Perhaps a good topic to start with, since you've obviously figured out how
to use the C++ docs is little guide for using the C++ docs by someone who
doesn't know C++. (While the pain is still fresh in your memory :wink:

Let me know what you think about these ideas. I've been planning on

putting

a Wiki (a MoinMoin actually) on the wxPython website. User contributed

mini

how-to's and FAQ answers are probably a great thing to get it started

with.

--
Robin Dunn
Software Craftsman
robin@AllDunn.com Java give you jitters?
http://wxPython.org Relax with wxPython!

_______________________________________________
wxpython-users mailing list
wxpython-users@lists.wxwindows.org
http://lists.wxwindows.org/mailman/listinfo/wxpython-users

4

I was sort of thinking along the same lines. When there is a lack of docs
then each of us goes through a learning curve and somewhere in the back of
our minds we feel that it would be great to share that experience.

So how about an open forum type web site where people could add what they
have learnt and their understanding of how wxPython/wxWindows works to
the relevant sections of the frameworks documentation? All Robin/Juilan et
all would have to do is to just act as editors and perhaps the creators of
the initital outline and fix any errors in the documentation as it
evolves. As it evolves it will help bring newcomers up to speed even
faster. If the open source model works for complex software then it surely
must work for its documentation. Perhaps zope could be used for the
underlying authoring system. With a large % of users writing a few notes
here and there the documentation will become comprehensive and grow
quickly.

I am using the boa constuctor as a learning tool, design something and see
what code it generates after I figured out how it worked. Boa is pretty
cool and awesome.

···

On Tue, 3 Apr 2001 13:39:47 +1200 Erik Westra <ewestra@wave.co.nz> wrote:

I see from the mailing list archives that various people have raised
this
bugaboo in the past, but nothing seems to have come of it. If there
really
isn't anyone working on extending the wxPython docs, I'd be keen to
tackle it
myself -- I've written quite a few tutorials and reference manuals in
the past, so I'm
not exactly a neophyte in this regard...and since I don't know C++ this
is
probably the best contribution I could make to the wxPython project.

Now, I'm obviously still learning wxPython myself, but I've been
collecting
notes about how the various parts of wxPython work, and in particular
the
things which would be confusing to a novice. If it'd be worthwhile, I'd
be
happy to keep writing notes over the next few months as I learn, and
then put
it all together into a new-user tutorial. A detailed user's guide, a
cookbook
of common UI tasks and how to achieve them, and maybe even a
Python-specific
reference, might all be possible after that...

--
  .-. | Bakki Kudva__________________Open Source EDMS______
  oo> > Navaco ph: 814-833-2592
/`'\ | 420 Pasadena Drive fax: 603-947-5747
(\_;/) | Erie, PA 16505 http://www.navaco.com/

5

Hi Robin,

You've read my mind. This is almost the same as the outline of the book I'm
writing! (And before you ask, it's in the eary stages still and no, there's
nothing to look at yet. :wink:

Wow, you have the time to work on a book as well as everything else? I'm
impressed!

I actually sat down last night and began thinking of an outline for a possible
"wxPython Users' Guide", combining all my ideas into a single document. For
what it's worth, here's what I came up with:

···

=============================================================================

           wxPython User's Guide

1. Quick Tour

  A brief description of the wxPython toolkit, what it is, what it does,
  and the different UI capabilities it provides.

2. Getting Started

  How to get the wxPython toolkit. Installing on various platforms. The
  www.wxpython.org web site. Building and running "hello world".

3. Learning wxPython

  Starts with a conceptual overview of a wxPython application, followed
  by a staged series of increasingly-complex tutorials covering the main
  aspects of the wxPython toolkit. Aimed at teaching what every wxPython
  user needs to know. Doesn't cover the more esoteric/advanced concepts,
  and focusses mainly on providing a introduction to a part of wxPython,
  followed by one or more examples with with a description of how each
  example works.

4. wxPython Cookbook

  An in-depth, "How-to"-oriented series of chapters covering every main
  task a GUI needs to accomplish, and how to do it in wxPython. Topics
  would include:

      Working with windows
      Working with menus
      Laying out elements in a window
      Accepting user input
      Responding to user actions
      Dialog boxes
      How to use fonts
      Using colour
      Customised Drawing
      Printing
      Debugging
      Deployment
      Cross-platform issues
      ...etc etc

  There will be a lot of chapters here!

5. wxPython Reference

  A python-ised version of the current wxWindows reference, possibly
  annotated to make it easier for wxPython users. Followed by a detailed
  cross-reference index, so you can quickly find what you need.

Glossary
Appendices???
Index

=============================================================================

Just thought I'd post it so you can see what I where my thinking was heading...
maybe this could tie in somehow with the wxPython mini how-to you mention
below??? It seems to me that the learning/cookbook/reference breakdown could
be a useful way of organising the overall documentation...

Anyway, I guess I should move this thread over to wxPython-docs and introduce
myself over there!

> Now, I'm obviously still learning wxPython myself, but I've been collecting
> notes about how the various parts of wxPython work, and in particular the
> things which would be confusing to a novice. If it'd be worthwhile, I'd be
> happy to keep writing notes over the next few months as I learn, and then
> put it all together into a new-user tutorial.

I think it would be very worthwile, but why wait a few months? If each
thing could be made into a standalone mini how-to then they could be put on
the website as you do them and people could start benefiting right away. It
may even inspire other people to start doing it too.

That's a great idea. I'll probably have to wait about three weeks before I
can start, since I have an exam coming up, but I'll see what I can do...

There is also the possibility, as Lucas Bruand is doing, of doing a more
formal Python How-To to become part of the collection at
http://py-howto.sourceforge.net/. You can see some conversation about it as
it progresses on the new wxPython-docs mail list at
http://lists.wxwindows.org/mailman/listinfo/wxpython-docs

Thanks for pointing me in the right direction -- the draft looks good, and is
definitely something I'd like to contribute towards...I'll get in touch with
Lucas directly...

BTW, I didn't notice a reference to the HOWTO on the main wxPython web site.
Is that just because you haven't gotten around to it, or because you don't want
to make this public quite yet?

> myself -- I've written quite a few tutorials and reference manuals in the
past, so I'm
> not exactly a neophyte in this regard...and since I don't know C++ this is
> probably the best contribution I could make to the wxPython project.

Perhaps a good topic to start with, since you've obviously figured out how
to use the C++ docs is little guide for using the C++ docs by someone who
doesn't know C++. (While the pain is still fresh in your memory :wink:

Yup, I can see the advantage of a guide like that Unfortunately, I do know C,
so the process wasn't all that painful for me...but I can well imagine how hard
it would be for someone who doesn't know C or C++ at all! I'll have a go and
see what I can come up with for you...

Let me know what you think about these ideas. I've been planning on putting
a Wiki (a MoinMoin actually) on the wxPython website. User contributed mini
how-to's and FAQ answers are probably a great thing to get it started with.

Sounds great!

- Erik.

6

A collaborative documentation project for wxPython is a great idea.

How about setting up a wiki as the forum for doing so? In the lab where I
work we've recently setup an internal wiki as a sort of electronic
chalkboard for research collaborations. It's working very well and provides
good mechanisms for providing descriptions as well as little snippets or
examples.

MoinMoin ( http://moin.sourceforge.net ) is a nice wiki implementation
written in Python.

If the completely open nature of wikis was considered "too open" it
shouldn't be hard to setup write access only to list-subscribers (or some
smaller subset of folks). However, this would seem to go against the Wiki
nature and would discourage truly free-flowing contributions.

Whaddaya think?

--Paul

7

Hi Lucas,

I think it would be a good thing to have a standard format for wxPython
documentation. Even if everyone don't stick to it... If anyone is interested
in adding things in the Howto, you are welcome...

I agree completely! Let's move this thread over to wxpython-docs...

- Erik.

8

Hi Bakki,

I was sort of thinking along the same lines. When there is a lack of docs
then each of us goes through a learning curve and somewhere in the back of
our minds we feel that it would be great to share that experience.

Indeed.

So how about an open forum type web site where people could add what they
have learnt and their understanding of how wxPython/wxWindows works to
the relevant sections of the frameworks documentation? All Robin/Juilan et
all would have to do is to just act as editors and perhaps the creators of
the initital outline and fix any errors in the documentation as it
evolves. As it evolves it will help bring newcomers up to speed even
faster. If the open source model works for complex software then it surely
must work for its documentation. Perhaps zope could be used for the
underlying authoring system. With a large % of users writing a few notes
here and there the documentation will become comprehensive and grow
quickly.

This sounds almost exactly like the Wiki/MoinMoin system Robin was talking
about in his earlier E-Mail, where users could contribute their own
documentation and FAQ answers, and everything would be automatically
published...

I am using the boa constuctor as a learning tool, design something and see
what code it generates after I figured out how it worked. Boa is pretty
cool and awesome.

Well, I tend to avoid RAD tools myself, as I feel they clutter my code and
often end up with less-than-optimal results (eg, fixed screen coordinates
rather than using sizers, so a program looks good on one platform but not on
another -- I've been stung by this in the past). But that's just my personal
preference! Maybe you'd be a good person to contribute some docs about using
Boa Constructor to the wxPython how-to???

- Erik.

9

A collaborative documentation project for wxPython is a great idea.

How about setting up a wiki as the forum for doing so?

I'm already working on setting it up. Should be ready by tomorrow if I can
squeeze out some more time to spend on it tonight.

MoinMoin ( http://moin.sourceforge.net ) is a nice wiki implementation
written in Python.

Yep.

If the completely open nature of wikis was considered "too open" it

It is a bit too open for my tastes but I'm willing to give it a try. I'm
going to draft a set of rules that will be part of the Wiki. If everybody
behaves and follows the rules then I won't worry about write-access
restrictions.

···

--
Robin Dunn
Software Craftsman
robin@AllDunn.com Java give you jitters?
http://wxPython.org Relax with wxPython!

10

Wow, you have the time to work on a book as well as everything else? I'm
impressed!

It's proving to be a MUCH larger task than I had anticipated, but I really
want to get it done.

I actually sat down last night and began thinking of an outline for a

possible

"wxPython Users' Guide", combining all my ideas into a single document.

For

what it's worth, here's what I came up with:

Thanks!

...

> There is also the possibility, as Lucas Bruand is doing, of doing a more
> formal Python How-To to become part of the collection at
> http://py-howto.sourceforge.net/. You can see some conversation about

it as

> it progresses on the new wxPython-docs mail list at
> http://lists.wxwindows.org/mailman/listinfo/wxpython-docs

Thanks for pointing me in the right direction -- the draft looks good, and

is

definitely something I'd like to contribute towards...I'll get in touch

with

Lucas directly...

BTW, I didn't notice a reference to the HOWTO on the main wxPython web

site.

Is that just because you haven't gotten around to it, or because you don't

want

to make this public quite yet?

It still needs some polish before Lucas feels comfortable about letting the
world see it, plus I still owe him some sample code to write about...

···

--
Robin Dunn
Software Craftsman
robin@AllDunn.com Java give you jitters?
http://wxPython.org Relax with wxPython!

11

           wxPython User's Guide

1. Quick Tour

  A brief description of the wxPython toolkit, what it is, what it does,
  and the different UI capabilities it provides.

2. Getting Started

  How to get the wxPython toolkit. Installing on various platforms. The
  www.wxpython.org web site. Building and running "hello world".

In between these two how about a section on the general architecture of
wxWindows? How the classes are laid out and how they use each other, any
other info on the design patterns used, the event model and other related
subjects aimed at giving an overview. General programming guidelines which
apply to most classes. (eg. the way the menus are appended to a menubar is
similar to the way buttons are appended to a toolbar etc.)

More a picture of the forest before we start looking at individual trees.

···

On Wed, 4 Apr 2001 08:12:28 +1200 Erik Westra <ewestra@wave.co.nz> wrote:

3. Learning wxPython

  Starts with a conceptual overview of a wxPython application, followed
  by a staged series of increasingly-complex tutorials covering the main

--
  .-. | Bakki Kudva__________________Open Source EDMS______
  oo> > Navaco ph: 814-833-2592
/`'\ | 420 Pasadena Drive fax: 603-947-5747
(\_;/) | Erie, PA 16505 http://www.navaco.com/

12

Hello Erik,

This sounds almost exactly like the Wiki/MoinMoin system Robin was
talking
about in his earlier E-Mail, where users could contribute their own
documentation and FAQ answers, and everything would be automatically
published...

I saw all the postings on Wiki/MoinMoin just after I had sent my msg off.
It is great news though that this is being done. Now we can all put in our
two cents worth into the docs.

Well, I tend to avoid RAD tools myself, as I feel they clutter my code
and
often end up with less-than-optimal results (eg, fixed screen
coordinates
rather than using sizers, so a program looks good on one platform but
not on
another -- I've been stung by this in the past). But that's just my
personal
preference! Maybe you'd be a good person to contribute some docs about
using
Boa Constructor to the wxPython how-to???

I'd be happy to and I will keep notes of my own travels through it. I
agree with you that RAD tools will produce suboptimal code. However I am
finding it useful as a first step to figure things out quickly. Ofcourse I
am not yet up the learning curve enough to appreciate nuances. All in all
I am delighted how active and full of ideas this community is.

As an aside, I noticed that guys like Eric Raymond have suggested making
wxPython the default GUI for Python. Does anyone on this list know where
Guido and the core team stand on this? That would be fantastic.

-bakki

···

On Wed, 4 Apr 2001 09:01:51 +1200 Erik Westra <ewestra@wave.co.nz> wrote:

--
  .-. | Bakki Kudva__________________Open Source EDMS______
  oo> > Navaco ph: 814-833-2592
/`'\ | 420 Pasadena Drive fax: 603-947-5747
(\_;/) | Erie, PA 16505 http://www.navaco.com/

13

Hi Bakki,

> wxPython User's Guide
>
> 1. Quick Tour
>
> A brief description of the wxPython toolkit, what it is, what it does,
> and the different UI capabilities it provides.
>
> 2. Getting Started
>
> How to get the wxPython toolkit. Installing on various platforms. The
> www.wxpython.org web site. Building and running "hello world".

In between these two how about a section on the general architecture of
wxWindows? How the classes are laid out and how they use each other, any
other info on the design patterns used, the event model and other related
subjects aimed at giving an overview. General programming guidelines which
apply to most classes. (eg. the way the menus are appended to a menubar is
similar to the way buttons are appended to a toolbar etc.)

Yes, I agree: we need to describe somewhere the overall architecture of
wxPython, in pretty much exactly the way you've described: how the classes
relate to each other, event models, general programming guidelines, etc etc.
The thing is, the notion of a "wxPython Users Guide" has now migrated to a more
dynamic online system for building documentation -- the "wxPyWiki" which Robin
has set up:

  http://wxpython.org/cgi-bin/wiki

We've now started putting various articles up on this system -- it's a great
way of working collaboratively on a number of documents in progress. Have you
had a chance to check it out yet? Eventually, I'm sure, the material we come
up with will be published in a more traditional way, but for now this is a
great way of evolving and building the docs...

More a picture of the forest before we start looking at individual trees.

Yes, indeed. Great idea! At the very least, we should create a empty
placeholder within wxPyWiki for this "Conceptual wxPython Overview"
page...then whoever has the time and inclination can have a go at writing it.
I don't suppose you'd be keen would you?

Cheers,

- Erik.

14

Hi Erik,

I did check out the wiki web and it is the right way to generate these
docs. I would really like to contribute to the effort. I am however still
on an early stage of the learning curve. But as I learn and understand the
concepts I wouldn't mind submitting some material. Right now I seem to be
spending a lot of time with the HTML docs for wxWindows and trying to
digest all the api calls. When I have my own "conceptual overview" clear
in my mind I'd love to write it up to help others who are following.

-bakki

···

On Sun, 8 Apr 2001 18:47:24 +1200 Erik Westra <ewestra@wave.co.nz> wrote:

Yes, I agree: we need to describe somewhere the overall architecture of
wxPython, in pretty much exactly the way you've described: how the
classes
relate to each other, event models, general programming guidelines, etc
etc.
The thing is, the notion of a "wxPython Users Guide" has now migrated to
a more
dynamic online system for building documentation -- the "wxPyWiki" which
Robin
has set up:

  http://wxpython.org/cgi-bin/wiki

We've now started putting various articles up on this system -- it's a
great
way of working collaboratively on a number of documents in progress.
Have you
had a chance to check it out yet? Eventually, I'm sure, the material we
come
up with will be published in a more traditional way, but for now this is
a
great way of evolving and building the docs...

> More a picture of the forest before we start looking at individual
trees.

Yes, indeed. Great idea! At the very least, we should create a empty
placeholder within wxPyWiki for this "Conceptual wxPython Overview"
page...then whoever has the time and inclination can have a go at
writing it.
I don't suppose you'd be keen would you?

Cheers,

- Erik.

--
  .-. | Bakki Kudva__________________Open Source EDMS______
  oo> > Navaco ph: 814-833-2592
/`'\ | 420 Pasadena Drive fax: 603-947-5747
(\_;/) | Erie, PA 16505 http://www.navaco.com/

15

Hi Bakki,

I did check out the wiki web and it is the right way to generate these
docs. I would really like to contribute to the effort. I am however still
on an early stage of the learning curve. But as I learn and understand the
concepts I wouldn't mind submitting some material. Right now I seem to be
spending a lot of time with the HTML docs for wxWindows and trying to
digest all the api calls. When I have my own "conceptual overview" clear
in my mind I'd love to write it up to help others who are following.

That would be excellent, thanks. Assuming that Lucas Bruand (the person
who'se been working on the "Getting Started" part of the docs) is happy with
it, I'll go ahead and create an initial outline for a new "wxPython Concepts"
page, and throw in whatever information I can quickly knock together. You
could then use that as a starting point, if you wanted to...

Thanks,

- Erik.