Phoenix documentation

With regards to Andrea's points on the user list.

ScreenShots
I will continue doing more screen shots and send them in the original size. Andrea, naming the images by the class name is fine, right? If there are multiple ones for the same class I add just a number.

Would be great if someone could do screen shots on *nix and/or Mac.

Documentation changes
Would like to help here, but it looks that this is all "extractors.py" work and this very much looks like it is over my head. However I can be convinced otherwise:).

Werner

Hi Werner,

With regards to Andrea's points on the user list.

ScreenShots
I will continue doing more screen shots and send them in the original size.
Andrea, naming the images by the class name is fine, right? If there are
multiple ones for the same class I add just a number.

This is perfectly fine for me, although if you could name in the
following way it would be better:

- If it 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

and so on. What you are doing is of extremely great help.

Would be great if someone could do screen shots on *nix and/or Mac.

Yes, this is still on the todo-list for someone to step in...

Documentation changes
Would like to help here, but it looks that this is all "extractors.py" work
and this very much looks like it is over my head. However I can be
convinced otherwise:).

I believe it is much less complicated than you think. All the
docstrings for pure-Python classes/methods/functions are exposed in
the Python files themselves, for example on line 250 here:

http://svn.wxwidgets.org/viewvc/wx/wxPython/Phoenix/trunk/etg/_core.py?revision=70092&view=markup

It would be enough to edit the "doc" parameter for the "addPyClass"
and "PyFunctionDef" calls to make it more ReST-compliant, i.e. adding
the proper :ref:, :class:, :meth: roles, adding the :param: roles and
definition where it is missing and harmonize the Sphinx admonitions
(i.e., :see: ==> .. seealso::, :note: ==> .. note:: and so on).

Otherwise, I would say the bulk of wx.lib/wx.tools is in great need of
documentation-refactoring if you prefer to work on classic Python
docstrings. Any help in any direction is appreciated, so I guess you
may just choose what you like more :smiley:

I'll upload my sources this evening with some more explanations.

Andrea.

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

···

On 30 December 2011 12:21, werner wrote:

Hi Andrea,

...

- If it 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

Noted and will try to remember;-)

...

I believe it is much less complicated than you think. All the
docstrings for pure-Python classes/methods/functions are exposed in
the Python files themselves, for example on line 250 here:

http://svn.wxwidgets.org/viewvc/wx/wxPython/Phoenix/trunk/etg/_core.py?revision=70092&view=markup

It would be enough to edit the "doc" parameter for the "addPyClass"
and "PyFunctionDef" calls to make it more ReST-compliant, i.e. adding
the proper :ref:, :class:, :meth: roles, adding the :param: roles and
definition where it is missing and harmonize the Sphinx admonitions
(i.e., :see: ==> .. seealso::, :note: ==> .. note:: and so on).

Yeap, I should be able to handle this. Will do one or two next week and post the patch for it for you and Robin to check.

How can this be organized so we don't get to the point where multiple people work on the same docs? Maybe a wiki page linked from the Phoenix one where one makes an entry along the lines "etg._core - Werner B." or "etc._* - Werner B", the later meaning that I started work on all files starting with "_" - just in case the wild card was not understandable:-)

Otherwise, I would say the bulk of wx.lib/wx.tools is in great need of
documentation-refactoring if you prefer to work on classic Python
docstrings. Any help in any direction is appreciated, so I guess you
may just choose what you like more :smiley:

That might be possible to.

Werner

···

On 12/30/2011 12:46 PM, Andrea Gavana wrote:

Hi Andrea and Robin,

A few questions to doc changes.

- What are the valid "type" values for :param ? something:, is it all the Python types (http://docs.python.org/library/types.html) or only a sub-set?
- What type should one use e.g. for the "callableObj" on CallAfter?
- What to use for return? Should we always do:

:returns: with description
:rtype: int

or are we using just one of them.

- Do we put the :param ....: before documentation text or after. I put it after in the attached sample patch, but wonder if before wouldn't be better, e.g. for call tips in IDE's.
- Do methods like "HasRun" and "GetResult" get documentation as I did in the patch or not?

Werner

sample.patch (3.38 KB)

Hi Werner,

Hi Andrea and Robin,

A few questions to doc changes.

- What are the valid "type" values for :param ? something:, is it all the
Python types (types — Dynamic type creation and names for built-in types — Python 3.13.0 documentation) or only a sub-set?

As far as I know, you can use whatever you want as long as it makes
sense, although it would be better to stick with standard Python types
plus the wx classes/enums.

- What type should one use e.g. for the "callableObj" on CallAfter?

I would use object, but it is a debatable choice. I am not sure we can
use something like "callable" as a type, but you can try and we'll
rebuild the docs and we'll see what happens...

- What to use for return? Should we always do:

:returns: with description
:rtype: int

or are we using just one of them.

If the return description is meaningful (i.e., more than a couple of
words), then I would say use both. Otherwise just use :rtype: if
something is returned,

- Do we put the :param ....: before documentation text or after. I put it
after in the attached sample patch, but wonder if before wouldn't be better,
e.g. for call tips in IDE's.

No, please don't put them before... it is completely against the
current wxWidgets docs (from which the Sphinx ones are generated) and
all the other pure-Python docs I know of (including Editra, AGW,
standard library etc...).

- Do methods like "HasRun" and "GetResult" get documentation as I did in the
patch or not?

To me your patch looks perfect. I am not sure we should document the
*args and **kwargs parameters, but I'll leave that decision to the
Boss.

Thank you!

Andrea.

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

···

On 30 December 2011 19:08, werner wrote:

dataview.dataviewctrl.png

Wait until you see the file name for wx.lib.agw.aui.aui_switcherdialog

Two dots in a filename is certainly not very cute.

A dot is a perfectly valid character in a file name. Cute or not, is
one degree above zero importance to me in this case, as it is
convenient to generate the Sphinx docs and once you get the HTML, no
one cares about the embedded images file names.

Andrea.

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

import PyQt4.QtGui

Traceback (most recent call last):
File "<interactive input>", line 1, in <module>
ImportError: No module named PyQt4.QtGui

import pygtk

Traceback (most recent call last):
File "<interactive input>", line 1, in <module>
ImportError: No module named pygtk

···

On 30 December 2011 19:28, jmfauth wrote:

import wx

Hi Werner,

Could you send me a sample of your screenshots? Maybe I can do some from my Ubuntu VM.

  • Mike
···

On Fri, Dec 30, 2011 at 5:21 AM, werner wbruhin@free.fr wrote:

With regards to Andrea’s points on the user list.

ScreenShots

I will continue doing more screen shots and send them in the original size. Andrea, naming the images by the class name is fine, right? If there are multiple ones for the same class I add just a number.

Would be great if someone could do screen shots on *nix and/or Mac.

Documentation changes

Would like to help here, but it looks that this is all “extractors.py” work and this very much looks like it is over my head. However I can be convinced otherwise:).

Werner

To unsubscribe, send email to wxPython-dev+unsubscribe@googlegroups.com

or visit http://groups.google.com/group/wxPython-dev?hl=en

Mike Driscoll

Blog: http://blog.pythonlibrary.org

Agreed.

···

On 12/30/11 11:59 AM, Andrea Gavana wrote:

On 30 December 2011 19:28, jmfauth wrote:

dataview.dataviewctrl.png

Wait until you see the file name for wx.lib.agw.aui.aui_switcherdialog

Two dots in a filename is certainly not very cute.

A dot is a perfectly valid character in a file name. Cute or not, is
one degree above zero importance to me in this case, as it is
convenient to generate the Sphinx docs and once you get the HTML, no
one cares about the embedded images file names.

--
Robin Dunn
Software Craftsman

I haven't paid any attention to it before now but there is a tool that the wxWidgets folks use to automatically grab screenshots of controls for the docs. It is located in wxTrac has been migrated to GitHub Issues - wxWidgets.

Perhaps that could be used, or maybe convert it to a Python tool, to automate the grabbing of screenshots for us too.

···

On 12/30/11 12:13 PM, Mike Driscoll wrote:

Hi Werner,

Could you send me a sample of your screenshots? Maybe I can do some from
my Ubuntu VM.

--
Robin Dunn
Software Craftsman

Hi Mike,

Hi Werner,

Could you send me a sample of your screenshots? Maybe I can do some from my Ubuntu VM.

See attached.

I just run each demo and used IrfanView to take a screen shot of the frame coming up or if the widget is shown within the demo frame then I just take that section of the screen.

Name the files as per Andrea's post and send them off-list to him, he will do the rest.

Werner

winWidgets.zip (186 KB)

···

On 12/30/2011 09:13 PM, Mike Driscoll wrote:

Hi Robin,

Hi Werner,

Could you send me a sample of your screenshots? Maybe I can do some from
my Ubuntu VM.

I haven't paid any attention to it before now but there is a tool that the wxWidgets folks use to automatically grab screenshots of controls for the docs. It is located in wxTrac has been migrated to GitHub Issues - wxWidgets.

No idea if this could be adapted to wxPython as I don't know C++ at all.

Perhaps that could be used, or maybe convert it to a Python tool, to automate the grabbing of screenshots for us too.

As there are currently 267 demo files to capture three times it could definitely be of help. So, I had a go at it, but some hurdles to over come, the attached script is what I have so far - needs more work.

My problems (only tried on Win7):

1. I attached the about.pgn which is generated, as you can see I only capture the frame and the button and the other stuff doesn't show. I must have a very basic/stupid problem in the method "captureScreenshot" in the attached script.

2. How would we deal with all the demos which have a button "please press me" or similar to actually show the demo? Maybe have a method "doButton" or similar which returns the actual demo window?

3. I also get an ImportError on ActiveX_FlashWindow.py with regards to comtypes (which I don't have), but I thought my try/except in doCapture should catch.

4. naming of files is another thing to resolve, currently I just lower case the demo file name, but will need to come up with something to make live easier for Andrea. Maybe a dict with {demofilename: expectedname, } or something similar.

Hope you could give me some tips on how to resolve things, especially 1 and 2.

Werner

screencapturedemo.py (3.92 KB)

···

On 12/30/2011 09:24 PM, Robin Dunn wrote:

On 12/30/11 12:13 PM, Mike Driscoll wrote:

Oops, sorry for sending the large file to the list, intend was to send it to Mike only.

Werner

...

2. How would we deal with all the demos which have a button "please press me" or similar to actually show the demo? Maybe have a method "doButton" or similar which returns the actual demo window?

or an alternative "runTest" which directly runs it instead of doing runTest and then doButton.

Werner

···

On 12/31/2011 02:36 PM, werner wrote:

Did a bit more testing and researching on this.

Found Ray's wiki page on this which helped a lot, but still not quite there.

If I run the capture from my script directly then I get some area of my desktop, if I create a runTestAlt in the demo and call the capture routine from there I get the area of the demo screen in question (see image of advancesplash) but it is not showing its content.

I also tried with a version where the capture script doesn't have a frame, with more code in runTestAlt to compensate for that, but no difference.

Current version of the script (adjust the demo/agw folder path and the two demo files (from the demo/agw folder I use for the test. I also attach the currently captured image.

Anyone has some tip on how to be get the actual demo screen captured.

Werner

screencapturedemo.py (5.43 KB)

advancedsplash.png

aquabutton.png

AdvancedSplash.py (1.91 KB)

AquaButton.py (4.69 KB)

Hi,

Very frustrating day but finally made some progress on this. My problem was trying to make this work Windows 7 running under Oracle VM - which just wouldn't work.

Running the attached under Windows 7 native works for me.

However only with modified demos, basically I added a runTestCapture method which is run from the capture script.

I would like some guidance on how to proceed.

- Is the modified demo approach acceptable?
- if yes, suggestions for appropriate naming of the method - doScreenCapture?
- how to deal with multiple demos in one file, e.g. AUI
- how to deal with demos with a button to be pressed for demo to show? Is the DoButton method I did acceptable or ....? see AdvancedSplash
- how to deal with demos which require multiple buttons to be pressed to get to the real demo, e.g. BaloonTip.
- image file name - I was thinking of changing the capture method in each demo to return the name to be used. Is this fine or should this list be centrally maintained, i.e. within the screencapture script?

Attached the script which does the generation, changed demos for AdvancedSplash and BallonTip (as sample) and the generated images.

Werner

screencapturedemo.py (4.72 KB)

advancedsplash.png

aquabutton.png

aui.png

balloontip.png

AdvancedSplash.py (1.79 KB)

BalloonTip.py (14.7 KB)

Hi everyone,

I changed the script to capture the demo screens a bit more, mainly to adapt to run on Ubuntu.

Noticed that the changed BalloonTip demo had some problems, but even after correcting them this demo does not like using wx.SafeYield at least on my setup (Ubuntu 11.04 with Python 2.7 and wxPython 2.8.12.0 and I use the XFCE desktop), it just hangs on that call, however I can manually close it but obviously this isn't helpful as I can't capture at that point.

AUI is fine, AdvanceSplash and AquaButton are not quit right, i.e. have strange artifacts in the image.

Werner

BalloonTip.py (14.7 KB)

screencapturedemo.py (5.8 KB)

If I comment line 259 which is the EVT_IDLE handler bind then the problem goes away.

Is there a "nicer" work around for this?

Werner

···

On 01/04/2012 09:20 PM, werner wrote:

Hi everyone,

I changed the script to capture the demo screens a bit more, mainly to adapt to run on Ubuntu.

Noticed that the changed BalloonTip demo had some problems, but even after correcting them this demo does not like using wx.SafeYield

The attached script works for me on Xubuntu and Windows 7 native, on Windows 7 in a VirtualBox I get artifacts on the screen shot images.

I would like to get this ready by the time Andrea comes back from vacation. However I don't want to go ahead and modify the demo scripts in a way which would not be accepted as a patch.

Robin, I hope you will be able to find some time to have a look at this stuff and give me some guide lines to follow. Or if you think I am going about this in bad/wrong way point me in any other direction, except anything to do with C++;-) .

Werner

screencapturedemo.py (5.37 KB)

Hi Werner,

The attached script works for me on Xubuntu and Windows 7 native, on Windows
7 in a VirtualBox I get artifacts on the screen shot images.

I would like to get this ready by the time Andrea comes back from vacation.
However I don't want to go ahead and modify the demo scripts in a way which
would not be accepted as a patch.

Robin, I hope you will be able to find some time to have a look at this
stuff and give me some guide lines to follow. Or if you think I am going
about this in bad/wrong way point me in any other direction, except anything
to do with C++;-) .

To me it seems like a nice approach, and I don't have anything against
modifying the demos themselves to accommodate for the
screenshots-taking code. As far as I am concerned, I'll happily
integrate your patches into the AGW demo codes. I guess we will just
wait and see what Robin has to say about this issue.

Robin: I have seen you worked on the Sphinx documentation generators.
As I just came back and I need to get up to speed again, could you
please re-summarize what still needs to be done/changed in the code to
better handle the documentation generation?

Thank you.

Andrea.

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

···

On 5 January 2012 15:14, werner wrote:

You've probably figured this all out by now, but the main thrust of my changes back then was to make it so you would not have to run *all* the etg scripts and generate all of the documentation input files every time you make a small change in one doxygen file or one etg file. Making one small change should only require that the one etg script be executed to generate just the intermediate file(s) that need to be updated to reflect that change in the source file. All of the other intermediate files left-over from prior runs of the etg scripts should still be present in the workspace and should still be useable for the next sphinx build of the docs. The various clean commands can be used to bring the workspace back to a pristine state if desired, but it should not be needed very often during normal development work. IOW, I want to keep the edit-->build-->test cycle as short as possible when working on the docs just like when working on the C++ code or whatever.

···

On 1/16/12 1:13 AM, Andrea Gavana wrote:

Robin: I have seen you worked on the Sphinx documentation generators.
As I just came back and I need to get up to speed again, could you
please re-summarize what still needs to be done/changed in the code to
better handle the documentation generation?

--
Robin Dunn
Software Craftsman