Sphinxed Phoenix Documentation (4)

Hi All,

    a new set of documentation pages are available for Phoenix
2.9.4.80 at http://xoomer.virgilio.it/infinity77/Phoenix/main.html.

This release includes:

1) Fixes on the problems reported by Werner on wx.EvtHandler (and
there were many others, hopefully they should be OK now);
2) Integration of Chris' samples on wx.GridBagSizer (see
http://xoomer.virgilio.it/infinity77/Phoenix/GridBagSizer.html#gridbagsizer).
If someone thinks the samples are still too verbose (i.e., long), I
can include them as separate downloads instead of inline samples in
the docs;
3) Start on the Documentation guidelines (see
http://xoomer.virgilio.it/infinity77/Phoenix/DocstringsGuidelines.html).
Please let me know if you feel I should add something else or expand
some issues; also, please feel free to criticize the standards;
4) I have integrated Werner's patches on _core.py and app.py for the docstrings.

Please let me know if you see anything strange.

Enjoy.

Andrea.

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

Good morning Andrea

Hi All,

...

Please let me know if you see anything strange.

A little spell error:
http://xoomer.virgilio.it/infinity77/Phoenix/DocstringsGuidelines.html

"which require manual input od the documentation"

'od' should be 'of'

In admonitions you mention "deprecated" shouldn't "versionadded" and "versionchanged" also be on there?

With regards to the contributed examples, what about having just a list of contributed example in the current place with a short description with a link which opens the sample in its own page.

BTW, have you given up or not found the time (to understand their javascript magic) to adapt some of the TurboGears theme stuff, especially keeping the table of content in view when scrolling would be very nice:)

Werner

···

On 01/04/2012 19:55, Andrea Gavana wrote:

Hi Werner,

Good morning Andrea

Hi All,

Please let me know if you see anything strange.

A little spell error:

http://xoomer.virgilio.it/infinity77/Phoenix/DocstringsGuidelines.html

“which require manual input od the documentation”

‘od’ should be ‘of’

Thanks, I’ll fix it up when I get back home.

In admonitions you mention “deprecated” shouldn’t “versionadded” and “versionchanged” also be on there?

They are, at the bottom of that section. I just thought they were less important (and also less visible) than the other ones, but I can put them back in the main list.

With regards to the contributed examples, what about having just a list of contributed example in the current place with a short description with a link which opens the sample in its own page.

That would be OK with me, I think I will do something like this:

  1. If the sample is more than 20 lines long, I’ll put it in a separate downloadable/browsable section; with a short description in the doc page;

  2. If it’s shorter than 20 lines, it gets included in the doc page.

That’s just rough and approximate, I’d be happy to hear other solutions.

BTW, have you given up or not found the time (to understand their javascript magic) to adapt some of the TurboGears theme stuff, especially keeping the table of content in view when scrolling would be very nice:)

I know, but I am really crappy at this javascript stuff. I’ll try and give it another go; if I can’t make it, someone else will have to look into it.

Andrea.

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

···

On 2 April 2012 10:49, Werner wrote:

On 01/04/2012 19:55, Andrea Gavana wrote:

Hi again,

...

    In admonitions you mention "deprecated" shouldn't "versionadded" and
    "versionchanged" also be on there?

They are, at the bottom of that section. I just thought they were less
important (and also less visible) than the other ones, but I can put
them back in the main list.

Oops, one should read to the end of things.

    With regards to the contributed examples, what about having just a
    list of contributed example in the current place with a short
    description with a link which opens the sample in its own page.

That would be OK with me, I think I will do something like this:

1) If the sample is more than 20 lines long, I'll put it in a separate
downloadable/browsable section; with a short description in the doc page;
2) If it's shorter than 20 lines, it gets included in the doc page.

That's just rough and approximate, I'd be happy to hear other solutions.

I would just do 1, but lets see what others think.

    BTW, have you given up or not found the time (to understand their
    javascript magic) to adapt some of the TurboGears theme stuff,
    especially keeping the table of content in view when scrolling would
    be very nice:)

I know, but I am really crappy at this javascript stuff. I'll try and
give it another go; if I can't make it, someone else will have to look
into it.

Great. In case you can't make it do you have a smallish test setup (I assume the full build takes quit a lot of time/stuff, no?) of the Phoenix doc which I could use to have a go at this.

Werner

···

On 02/04/2012 11:00, Andrea Gavana wrote:

Hi Andrea,

...

Please let me know if you see anything strange.

xoomer.virgilio.it/infinity77/Phoenix/RadioBox.html

The links for "Window", "Point", etc in the Info field list of __init__ don't work, i.e. I get this "http://xoom.virgilio.it/jump.html#window" page.

Werner

···

On 01/04/2012 19:55, Andrea Gavana wrote:

Andrea,

Nice work!

a new set of documentation pages are available for Phoenix
2.9.4.80 at http://xoomer.virgilio.it/infinity77/Phoenix/main.html.

2) Integration of Chris' samples on wx.GridBagSizer (see
http://xoomer.virgilio.it/infinity77/Phoenix/GridBagSizer.html#gridbagsizer).
If someone thinks the samples are still too verbose (i.e., long), I
can include them as separate downloads instead of inline samples in
the docs;

I think that's OK for ones that size, but yes, for larger ones they
should probably not be inline.

Does Sphinx allow some kind of "hiding"? i.e. some nifty javascript
that would let us put the example inline, but only show the first few
lines (or a description) be default, and the user could click on
something to get the whole thing?

I'm going to need to figure out a place to put larger examples, and
ones that show a concept, or how a few widgets work together, rather
than a single widget, class, whatever.

Maybe a whole section of the docs for small tests and examples?

-Chris

Please let me know if you see anything strange.

Looking good so far!

-Chris

···

--

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

HI Werner,

···

On 2 April 2012 17:47, Werner wrote:

Hi Andrea,

On 01/04/2012 19:55, Andrea Gavana wrote:

Please let me know if you see anything strange.

xoomer.virgilio.it/infinity77/Phoenix/RadioBox.html

The links for “Window”, “Point”, etc in the Info field list of init don’t work, i.e. I get this “http://xoom.virgilio.it/jump.html#window” page.

Thanks, should be fixed now, I have just uploaded the latest version (SVN version is the same though).

Andrea.

“Imagination Is The Only Weapon In The War Against Reality.”

http://xoomer.alice.it/infinity77/

Hi Chris,

Andrea,

Nice work!

a new set of documentation pages are available for Phoenix

2.9.4.80 at http://xoomer.virgilio.it/infinity77/Phoenix/main.html.

  1. Integration of Chris’ samples on wx.GridBagSizer (see

http://xoomer.virgilio.it/infinity77/Phoenix/GridBagSizer.html#gridbagsizer).

If someone thinks the samples are still too verbose (i.e., long), I

can include them as separate downloads instead of inline samples in

the docs;

I think that’s OK for ones that size, but yes, for larger ones they

should probably not be inline.

Does Sphinx allow some kind of “hiding”? i.e. some nifty javascript

that would let us put the example inline, but only show the first few

lines (or a description) be default, and the user could click on

something to get the whole thing?

Unfortunately there is nothing out of the box. I am pretty sure it can be done with JavaScript, but I am not that good in figuring out how to do it. The Python documentation has now a little “>>>” button which shows/hides the “>>>” prompt strings, so we may be able to borrow some ideas from there. But then again, I am not the right person to implement this feature.

I’m going to need to figure out a place to put larger examples, and

ones that show a concept, or how a few widgets work together, rather

than a single widget, class, whatever.

Maybe a whole section of the docs for small tests and examples?

I was thinking about linking them to the main documentation, and maybe putting a “Browse” and “Download” links close to the sample link to give the user the ability to see and/or download the code . This could easily be done with Sphinx. But I am open to all ideas in this sense.

Andrea.

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

···

On 2 April 2012 18:03, Chris Barker wrote:

Hi Werner & All,

···

On 2 April 2012 13:06, Werner wrote:

Hi again,

On 02/04/2012 11:00, Andrea Gavana wrote:

BTW, have you given up or not found the time (to understand their

javascript magic) to adapt some of the TurboGears theme stuff,

especially keeping the table of content in view when scrolling would

be very nice:)

I know, but I am really crappy at this javascript stuff. I’ll try and

give it another go; if I can’t make it, someone else will have to look

into it.

Great. In case you can’t make it do you have a smallish test setup (I assume the full build takes quit a lot of time/stuff, no?) of the Phoenix doc which I could use to have a go at this.

I managed to get it working, I have a local copy of the docs with a movable/collapsible sidebar which always stays visible, plus the scrolling page header with its own search button (pretty much like the TurboGears docs). I’ll upload the new version tonight.

Now someone will have to find a way to provide code folding through JavaScript for the contributed examples…

Andrea.

“Imagination Is The Only Weapon In The War Against Reality.”

http://xoomer.alice.it/infinity77/

Hi All,

Hi Werner & All,

Hi again,

BTW, have you given up or not found the time (to understand their

javascript magic) to adapt some of the TurboGears theme stuff,

especially keeping the table of content in view when scrolling would

be very nice:)

I know, but I am really crappy at this javascript stuff. I’ll try and

give it another go; if I can’t make it, someone else will have to look

into it.

Great. In case you can’t make it do you have a smallish test setup (I assume the full build takes quit a lot of time/stuff, no?) of the Phoenix doc which I could use to have a go at this.

I managed to get it working, I have a local copy of the docs with a movable/collapsible sidebar which always stays visible, plus the scrolling page header with its own search button (pretty much like the TurboGears docs). I’ll upload the new version tonight.

Now someone will have to find a way to provide code folding through JavaScript for the contributed examples…

OK, I managed to do both things in the end, and a bit more.

@Werner: the sidebar is now always visible, and it can be moved/collapsed. Also, the search field is now at the top scrolling header with the other top links, always visible.

It works in Chrome, IE7 and Firefox. I haven’t tested on other browsers.

@Chris: I have implemented an “accordion” behaviour for the contributed samples; they can be expanded/collapsed (default is collapsed) and they contain a link to download the samples (see http://xoomer.virgilio.it/infinity77/Phoenix/GridBagSizer.html)

It works in Chrome, IE7 and Firefox. I haven’t tested on other browsers. At some point we may want to start looking for sexier accordion images than the plain triangle ones, but I leave the graphics design part to someone else.

@Robin: there are a few issues I would like to ask for clarifications:

  1. It seems like wx.AboutDialog lives into an entity called “wx.adv”. Are we going to have a wx.adv package in Phoenix? If this is the case, I have to re-generate the docs and make the appropriate changes to the sphinx_generator file;

  2. There are 2 methods in the whole library for which the signature does not match the parameter list, namely:

class: wx.DropFilesEvent

method signature: init(id=0, files=None)

missing/misspelled parameter: noFiles

class: wx.Frame

method signature: SetStatusWidths(widths_field)

missing/misspelled parameter: n

I guess it is a simple tweaking of the extractors/etg files, but I am a bit afraid to touch them…

  1. I have made the following substitutions for parameter types and return types (in the docs only):

a) [‘Coord’, ‘Byte’, ‘FileOffset’, ‘short’, 'size_t, ‘time_t’, ‘IntPtr’, ‘UIntPtr’, ‘WindowID’] ==> Python integers (int);

b) [‘longlong’] ==> Python long integers (long)

c) [‘ArrayString’, ‘ArrayInt’, ‘ArrayDouble’] ==> [‘list of strings’, ‘list of integers’, ‘list of floats’]

Please let me know if I have to revert some of these changes.

Enjoy the new docs :slight_smile:

Andrea.

“Imagination Is The Only Weapon In The War Against Reality.”

http://xoomer.alice.it/infinity77/

···

On 3 April 2012 10:48, Andrea Gavana wrote:

On 2 April 2012 13:06, Werner wrote:

On 02/04/2012 11:00, Andrea Gavana wrote:

On Tue, Apr 3, 2012 at 11:35 AM, Andrea Gavana

@Chris: I have implemented an "accordion" behaviour for the contributed
samples; they can be expanded/collapsed (default is collapsed) and they
contain a link to download the samples
(see http://xoomer.virgilio.it/infinity77/Phoenix/GridBagSizer.html)

very cool! you are on a roll!

It works in Chrome, IE7 and Firefox. I haven't tested on other browsers.

It seems to work fine in Safari, too (which shares an engine with
Chrome, so no real surprise)

really nice work!

-Chris

At

···

some point we may want to start looking for sexier accordion images than the
plain triangle ones, but I leave the graphics design part to someone else.

@Robin: there are a few issues I would like to ask for clarifications:

1) It seems like wx.AboutDialog lives into an entity called "wx.adv". Are we
going to have a wx.adv package in Phoenix? If this is the case, I have to
re-generate the docs and make the appropriate changes to the
sphinx_generator file;

2) There are 2 methods in the whole library for which the signature does not
match the parameter list, namely:

class: wx.DropFilesEvent
method signature: __init__(id=0, files=None)
missing/misspelled parameter: noFiles

class: wx.Frame
method signature: SetStatusWidths(widths_field)
missing/misspelled parameter: n

I guess it is a simple tweaking of the extractors/etg files, but I am a bit
afraid to touch them...

3) I have made the following substitutions for parameter types and return
types (in the docs only):

a) ['Coord', 'Byte', 'FileOffset', 'short', 'size_t, 'time_t', 'IntPtr',
'UIntPtr', 'WindowID'] ==> Python integers (`int`);

b) ['longlong'] ==> Python long integers (`long`)

c) ['ArrayString', 'ArrayInt', 'ArrayDouble'] ==> ['list of strings', 'list
of integers', 'list of floats']

Please let me know if I have to revert some of these changes.

Enjoy the new docs :slight_smile:

Andrea.

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

--
To unsubscribe, send email to wxPython-dev+unsubscribe@googlegroups.com
or visit http://groups.google.com/group/wxPython-dev?hl=en

--

Christopher Barker, Ph.D.
Oceanographer

Emergency Response Division
NOAA/NOS/OR&R (206) 526-6959 voice
7600 Sand Point Way NE (206) 526-6329 fax
Seattle, WA 98115 (206) 526-6317 main reception

Chris.Barker@noaa.gov

Hi Chris,

···

On 3 April 2012 21:15, Chris Barker wrote:

On Tue, Apr 3, 2012 at 11:35 AM, Andrea Gavana

@Chris: I have implemented an “accordion” behaviour for the contributed

samples; they can be expanded/collapsed (default is collapsed) and they

contain a link to download the samples

(see http://xoomer.virgilio.it/infinity77/Phoenix/GridBagSizer.html)

very cool! you are on a roll!

It works in Chrome, IE7 and Firefox. I haven’t tested on other browsers.

It seems to work fine in Safari, too (which shares an engine with

Chrome, so no real surprise)

really nice work!

Thank you :slight_smile: . Please keep the samples coming!

Andrea.

“Imagination Is The Only Weapon In The War Against Reality.”

http://xoomer.alice.it/infinity77/

On Tue, Apr 3, 2012 at 11:35 AM, Andrea Gavana

@Chris: I have implemented an "accordion" behaviour for the contributed
samples; they can be expanded/collapsed (default is collapsed) and they
contain a link to download the samples
(see http://xoomer.virgilio.it/infinity77/Phoenix/GridBagSizer.html)

very cool! you are on a roll!

+10 :wink:

It works in Chrome, IE7 and Firefox. I haven't tested on other browsers.

It seems to work fine in Safari, too (which shares an engine with
Chrome, so no real surprise)

really nice work!

+10
:wink:
Werner

···

On 03/04/2012 21:15, Chris Barker wrote:

Hi Andrea,

Noticed a couple of small things.

http://xoomer.virgilio.it/infinity77/Phoenix/Button.html#button

- In the 4th para just after SetBitmapDisabled is "&c" shown
- Under the "BORDER_NONE" style the bitmap sizes are shown as 128128 instead of 128 x 128 etc.

Werner

Hi Werner,

Hi Andrea,

Noticed a couple of small things.

http://xoomer.virgilio.it/infinity77/Phoenix/Button.html#button

  • In the 4th para just after SetBitmapDisabled is “&c” shown

This is because the wxWidgets docs are written in that way:

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

I suppose the “&c” stands for “and company” (meaning all the other similar methods).

  • Under the “BORDER_NONE” style the bitmap sizes are shown as 128128 instead of 128 x 128 etc.

Thanks, that’s an unfortunate effect of removing the C++ “*” pointer stuff (or whatever is its name). I’ll fix it in the sphinx_generator.

Andrea.

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

···

On 4 April 2012 11:15, Werner wrote:

Didn’t know about that one.

.

I thought we/they should use new stuff and not “Archaic” or
“Obsolete” stuff

  • see French and Spanish sections on the above page.
    Werner
···

http://en.wiktionary.org/wiki/%26c

:wink:

Yep, a few of the core wx devs use it once in a while like I would use "etc." I've always assumed that it was a common abbreviation in Europe.

···

On 4/4/12 2:28 AM, Andrea Gavana wrote:

    - In the 4th para just after SetBitmapDisabled is "&c" shown

This is because the wxWidgets docs are written in that way:

wxWidgets: wxButton Class Reference

I suppose the "&c" stands for "and company" (meaning all the other
similar methods).

--
Robin Dunn
Software Craftsman

Hi,

···

On Sun, Apr 8, 2012 at 9:18 AM, Robin Dunn robin@alldunn.com wrote:

On 4/4/12 2:28 AM, Andrea Gavana wrote:

  • In the 4th para just after SetBitmapDisabled is “&c” shown

This is because the wxWidgets docs are written in that way:

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

I suppose the “&c” stands for “and company” (meaning all the other

similar methods).

Yep, a few of the core wx devs use it once in a while like I would use “etc.” I’ve always assumed that it was a common abbreviation in Europe.

A little off-topic, but just for interest: &c is not an abbreviation, but the ampersand was the ligature for “et” in older scripts. So it is still etc., it’s just that times have moved on since then.

Jon