Styles in widgets constructors + Some ideas on documentation

wxPython Users
1

Dear Andrea,

Thank you for your mail. I already knew the wxWidgets doc which is good and nice. But I must say I’m impressed by the matplotlib doc (I don’t know matplotlib at all).

In fact, I follow your arguments and understand them but I also understand the view point of the wxPython ‘bosses’ who are so close to the wxWidgets development. In any case, I can imagine that documentation maintenance is a huge effort on its own and there are only so many things one can do in 24 hours. I have really no idea how Doxygen or Sphynx work (I can only guess) but I also know there must be a huge deal of personal effort to build a good, complete and nice documentation.

Maybe we would need a kind of roadmap regarding the wxPython documentation ( I suppose that the wxWidget documentation has its own life). The reason I’m saying this is:

  1. On www.wxpython.org, there are 2 references to the documentation (Online wxDocs and New wxPyDocs.) and one needs to explore both to find out their own topics.

  2. The Online wxDocs documentation duplicates some chapters of the original wxWidgets documentation (e.g. Alphabetical Class Reference, or Functions or Class by Category). Other chapters have their own merits. This documentation is using - I guess - the same tool (epydoc ?) as older Python doc (I recognize the Home, Up a Level, Previous and Next icons).

  3. The New wxPyDocs documentation is interesting on its own (e.g. the class hierarchy) and the index would be a nice tool if it were not for 2 major drawbacks: 1) the repetition and 2) the hindrance of ‘thisown’, which I understand is a heritage of SWIG. Let me elaborate.

By repetition I mean:

Identifier X is a Class in Module Y;

Identifier X is a Class in Module Y, Class A;

Identifier X is a Class in Module Y, Class A, Class B;

Identifier X is a Class in Module Y, Class A, Class B, Class C;

etc …

The hindrance of ‘this own’ comes from the fact that it is listed as Class in Module M, in Class C, … for every conceivable module and every possible class. The ‘thisown’ identifier takes roughly 50% of the index page (which takes about 10 minutes to load on a slow 96 Kbps line and brings the explorer almost on its knees.)

For someone new to a subject, it is always best to have ONE central reference that points to various chapters without duplication. Take the example of the Class Hierarchy. I don’t know where is the base information but I suppose it is within the source code. The fact that the hierarchy can be represented graphically or as an indented text or as a tree control is independent of the base information. For instance, I would tend to believe that http://www.wxpython.org/docs/api/trees.html is THE reference for class hiererarchy and I guess / hope other representations (e.g. ) are in synch with it (the other day I saw a graphical representation but I lost the URL and can’t find it back).

Having said that, I reiterate my appreciation for all the efforts that are being done. I know it is a huge task (even with the support of tools) and I dare not criticize anything. However I agree with the idea that a roadmap does help uniting all the efforts and each one can then contribute a piece knowing that it fits within a broader plan.

All the best to you and to each wxPython aficionados.

Good evening, Rene

···

On Tue, Apr 21, 2009 at 10:13 AM, Andrea Gavana andrea.gavana@gmail.com wrote:

Hi Rene,

On Mon, Apr 20, 2009 at 6:22 PM, Rene Heymans wrote:

Hello Mike, Cody, & al.

About documentation, after many trials, I now go to Andrea’s documentation
site http://xoomer.virgilio.it/infinity77/wxPython/APIMain.html which I find

almost completely documented and foremost “visually attractive” (wait till
you get over 55 and you will have to abandon the sleek dense screen with
tiny letters … :wink: … ) . If there is something I can’t find, I go to

the wxWidgets docs (quite nice and complete too but in C++ jargon). The
other reason I like Andrea’s documentation is that it looks similar to the
new Python 3 doc.

The other day I saw a short note about doc mentionning Doxygen, Sphynx, and

… ?? can’t remember. I’m not at all versed in these documentation tools
but from a user point of view, next to accuracy and completeness I favour
very much beauty and elegance.

So do I :wink:

There was a discussion some time ago about the work I did with the
wxPython documentation and Sphinx: it looked like the general opinion
of wxPython users was that the Sphinx docs were reasonably good (in

terms of beauty and elegance, to use your wording), but it seemed to
me that the big wxPython bosses decided that, as wxWidgets is using
Doxygen, wxPython has to use Doxygen too. An example of how the
wxWidgets docs look like in the development trunk is here:

http://docs.wxwidgets.org/trunk/classwx_animation_ctrl.html

I have nothing against Doxygen, the only points I tried to make (and I

failed) were that Doxygen docs are no match for Sphinx docs (see an
example of what you can do with Sphinx here:
http://matplotlib.sourceforge.net/api/pyplot_api.html) and that, by

using Sphinx, we were bringing closer the wxPython docs and the Python
docs.

Andrea.

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

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