Sphinxed Phoenix Documentation (4)

[Andrea Gavana]

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/

[Werner]

Good morning Andrea

On 01/04/2012 19:55, Andrea Gavana wrote:
> 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

[Andrea Gavana]

Hi Werner,

On 2 April 2012 10:49, Werner wrote:

Good morning Andrea

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

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.

[Werner]

Hi again,

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

...

> 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

[Werner]

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.

Werner

[Chris Barker]

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....@noaa.gov

[Andrea Gavana]

HI Werner,

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

[Andrea Gavana]

Hi Chris,

On 2 April 2012 18:03, Chris Barker 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?

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 Gavana]

Hi Werner & All,

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 Gavana]

Hi All,

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...

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 :-)

[Chris Barker]

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

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

[Andrea Gavana]

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 :-) . Please keep the samples coming!

[Werner]

On 03/04/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!

+10 ;-)

>
>> 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
;-)
Werner

[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
- Under the "BORDER_NONE" style the bitmap sizes are shown as 128128
instead of 128 x 128 etc.

Werner

[Andrea Gavana]

Hi Werner,

On 4 April 2012 11:15, Werner 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

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. 

[Werner]

On 04/04/2012 11:28, Andrea Gavana wrote:

Hi Werner,

On 4 April 2012 11:15, Werner 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

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).

Didn't know about that one.

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

I thought we/they should use new stuff and not "Archaic" or "Obsolete" stuff ;-) - see French and Spanish sections on the above page.

Werner

[Robin Dunn]

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.

--
Robin Dunn
Software Craftsman
http://wxPython.org

[Jonathan Morgan]

Hi,

On Sun, Apr 8, 2012 at 9:18 AM, Robin Dunn <ro...@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