Sphinxed Phoenix Documentation 3
Andrea Gavana
I have tried to run the documentation builder
(sphinx_generator.py) using the lates SVN revision (70663) to try and
test the modifications I made to exclude some sections of the docs,
but I got the following:
...
C:\Python27\python.exe etg/iconloc.py --sip
C:\Python27\python.exe etg/iconbndl.py --sip
C:\Python27\python.exe etg/font.py --sip
Traceback (most recent call last):
File "etg/font.py", line 131, in <module>
run()
File "etg/font.py", line 52, in run
c.find('wxFont.flags').default = 'wxFONTFLAG_DEFAULT'
File "E:\Phoenix\wxPython\Phoenix\etgtools\extractors.py", line 90, in find
return item.find(tail)
File "E:\Phoenix\wxPython\Phoenix\etgtools\extractors.py", line 93, in find
(head, self.__class__.__name__, self.name))
etgtools.extractors.ExtractorError: Unable to find item named 'flags'
within MethodDef named 'wxFont'
Command 'C:\Python27\python.exe etg/font.py --sip' failed with exit code 1.
Now, I am not sure what the problem is as I am not really that expert
in the extraction part of the docs... Any chance you may take a look
at it?
Thank you.
Andrea.
"Imagination Is The Only Weapon In The War Against Reality."
http://xoomer.alice.it/infinity77/
Robin Dunn
> Hi Robin& All,
>
> I have tried to run the documentation builder
> (sphinx_generator.py) using the lates SVN revision (70663) to try and
> test the modifications I made to exclude some sections of the docs,
> but I got the following:
>
> ...
> C:\Python27\python.exe etg/iconloc.py --sip
> C:\Python27\python.exe etg/iconbndl.py --sip
> C:\Python27\python.exe etg/font.py --sip
> Traceback (most recent call last):
> File "etg/font.py", line 131, in<module>
> run()
> File "etg/font.py", line 52, in run
> c.find('wxFont.flags').default = 'wxFONTFLAG_DEFAULT'
> File "E:\Phoenix\wxPython\Phoenix\etgtools\extractors.py", line 90, in find
> return item.find(tail)
> File "E:\Phoenix\wxPython\Phoenix\etgtools\extractors.py", line 93, in find
> (head, self.__class__.__name__, self.name))
> etgtools.extractors.ExtractorError: Unable to find item named 'flags'
> within MethodDef named 'wxFont'
> Command 'C:\Python27\python.exe etg/font.py --sip' failed with exit code 1.
>
>
> Now, I am not sure what the problem is as I am not really that expert
> in the extraction part of the docs... Any chance you may take a look
> at it?
Did you also update the wxWidgets source tree and rerun the "build.py
dox" command to get updated XML?
--
Robin Dunn
Software Craftsman
http://wxPython.org
Andrea Gavana
Oops, my apologies, I forgot about that... either I am getting old or
I need some more sleep these days :-)
Anyway, I have re-run the dox command and I get this now:
C:\Python27\python.exe etg/toplevel.py --sip
C:\Python27\python.exe etg/dialog.py --sip
Traceback (most recent call last):
File "etg/dialog.py", line 67, in <module>
run()
File "etg/dialog.py", line 52, in run
c.find('OnSysColourChanged').ignore()
File "E:\Phoenix\wxPython\Phoenix\etgtools\extractors.py", line 93, in find
(head, self.__class__.__name__, self.name))
etgtools.extractors.ExtractorError: Unable to find item named
'OnSysColourChanged' within ClassDef named 'wxDialog'
Command 'C:\Python27\python.exe etg/dialog.py --sip' failed with exit code 1.
Robin Dunn
> Oops, my apologies, I forgot about that... either I am getting old or
> I need some more sleep these days :-)
Don't we all? ;-)
>
> Anyway, I have re-run the dox command and I get this now:
>
> etgtools.extractors.ExtractorError: Unable to find item named
> 'OnSysColourChanged' within ClassDef named 'wxDialog'
> Command 'C:\Python27\python.exe etg/dialog.py --sip' failed with exit code 1.
That's a change I hadn't pushed up to svn yet. Please update and try again.
Andrea Gavana
I have updated the Sphinx stuff: the image header should be back where
it was for the selected index pages. I have also added a rough way of
excluding unwanted sections from the docs (see the TextCtrl stuff as
it is right now).
With the help of Riaan Booysen (which managed to cleverly patch the
drifting-to-abandonware rst2pdf), I have almost got a PDF version of
the docs. Maybe in the next few days I'll be able to generate it.
Then, with HTML + CHM + PDF we will have all the possible format we
may need.
New documentation:
http://xoomer.virgilio.it/infinity77/Phoenix/main.html
TextCtrl specific:
http://xoomer.virgilio.it/infinity77/Phoenix/TextCtrl.html#textctrl
werner
On 28/02/2012 23:24, Andrea Gavana wrote:
> New documentation:
> http://xoomer.virgilio.it/infinity77/Phoenix/main.html TextCtrl specific:
That still shows "last updated 30 December 2011", what about putting the
generation date into the "SVN Revisions" box?
Robin, with regards to the Widget gallery I came up with a way to
automate the capture but it requires the demos to be changed to have a
method "runTestCapture" which is running the demo directly, i.e.
bypasses the button to click stuff we have on many demos. Would this
approach be fine with you, i.e. would you accept patches for this to the
demo or can you think of a better way doing the capture?
Werner
Andrea Gavana
On 29 February 2012 09:01, werner wrote:
> Hi Andrea,
>
>
> On 28/02/2012 23:24, Andrea Gavana wrote:
>>
>> New documentation: http://xoomer.virgilio.it/infinity77/Phoenix/main.html
>> TextCtrl specific:
>
> That still shows "last updated 30 December 2011", what about putting the
> generation date into the "SVN Revisions" box?
That's a bit strange... have you tried refreshing your browser's
cache? I can't access my website from work right now, but the docs I
just built tell me this:
Welcome to wxPython (Phoenix)'s documentation!
Welcome! This is the documentation for wxPython 2.9.3.74 (Phoenix),
last updated 29 February 2012.
I can put the generation date in the SVN box, no problems with that.
werner
> Hi Werner,
>
> On 29 February 2012 09:01, werner wrote:
>> Hi Andrea,
>>
>>
>> On 28/02/2012 23:24, Andrea Gavana wrote:
>>> New documentation: http://xoomer.virgilio.it/infinity77/Phoenix/main.html
>>> TextCtrl specific:
>> That still shows "last updated 30 December 2011", what about putting the
>> generation date into the "SVN Revisions" box?
> That's a bit strange... have you tried refreshing your browser's
> cache? I can't access my website from work right now, but the docs I
> just built tell me this:
>
> Welcome to wxPython (Phoenix)'s documentation!
>
> Welcome! This is the documentation for wxPython 2.9.3.74 (Phoenix),
> last updated 29 February 2012.
>
>
> I can put the generation date in the SVN box, no problems with that.
Werner
werner
On 28/02/2012 23:24, Andrea Gavana wrote:
...
> With the help of Riaan Booysen (which managed to cleverly patch the
> drifting-to-abandonware rst2pdf), I have almost got a PDF version of
> the docs. Maybe in the next few days I'll be able to generate it.
> Then, with HTML + CHM + PDF we will have all the possible format we
> may need.
Just noted that Christoph Zwerschke (TurboGears) is now a commiter on
rst2pdf and he seems more active then Roberto, maybe reposting the issue
with the patch might get it included.
Werner
Andrea Gavana
I have tried with the patches I got from Riaan, I have got much
further this time, but rst2pdf still fails with this nice message:
...
File "C:\Python27\lib\site-packages\PIL\Image.py", line 1952, in open
IOError: [Errno 24] Too many open files:
'C:\\MyProjects\\Phoenix\\Phoenix\\docs\\sphinx\\_static\\images\\sphinxdocs\\property_summary.png'
FAILED
I am going crazy trying to find out where the hell all these files are
getting opened but not closed.
werner
http://two.pairlist.net/pipermail/reportlab-users/2008-August/007122.html
Hope this is helpful
Werner
werner
On 29/02/2012 10:30, werner wrote:
>> further this time, but rst2pdf still fails with this nice message:
>>
>> ...
>> File "C:\Python27\lib\site-packages\PIL\Image.py", line 1952, in open
>> IOError: [Errno 24] Too many open files:
>> 'C:\\MyProjects\\Phoenix\\Phoenix\\docs\\sphinx\\_static\\images\\sphinxdocs\\property_summary.png'
>>
>> FAILED
>>
>> I am going crazy trying to find out where the hell all these files are
>> getting opened but not closed.
> I have tried with the patches I got from Riaan, I have got much
> googling for "too many open files PIL" points to some issues with
> reportlab.
>
> http://two.pairlist.net/pipermail/reportlab-users/2008-August/007122.html
>
Check the comments in 'imageReaderFlags' in rl_config.py in your
reportlab install.
Werner
Andrea Gavana
Thank you for that, it seems that now the build is progressing much
better... OK, it has successfully finished right now. Thanks Werner!
It doesn't look amazing like the HTML version, but I guess some
improvement can be made by tweaking the conf.py settings. I'll try and
do that.
werner
> Hi Werner,
>
> On 29 February 2012 10:36, werner wrote:
>> Me again,
>>
>>
>> On 29/02/2012 10:30, werner wrote:
>>
>>>> further this time, but rst2pdf still fails with this nice message:
>>>>
>>>> ...
>>>> File "C:\Python27\lib\site-packages\PIL\Image.py", line 1952, in open
>>>> IOError: [Errno 24] Too many open files:
>>>>
>>>> 'C:\\MyProjects\\Phoenix\\Phoenix\\docs\\sphinx\\_static\\images\\sphinxdocs\\property_summary.png'
>>>> FAILED
>>>>
>>>> I am going crazy trying to find out where the hell all these files are
>>>> getting opened but not closed.
>>> I have tried with the patches I got from Riaan, I have got much
>>> googling for "too many open files PIL" points to some issues with
>>> reportlab.
>>>
>>> http://two.pairlist.net/pipermail/reportlab-users/2008-August/007122.html
>>>
>> Check the comments in 'imageReaderFlags' in rl_config.py in your reportlab
>> install.
> Thank you for that, it seems that now the build is progressing much
> better... OK, it has successfully finished right now. Thanks Werner!
>
> It doesn't look amazing like the HTML version, but I guess some
> improvement can be made by tweaking the conf.py settings. I'll try and
> do that.
is for off-line reading maybe ePub should be considered, which I
understand adapts better to different devices (iPad/Tablette, smartphone
...).
My xMas pressy was an iPad, so just looked at the Phoenix doc on it and
it looks pretty neat. Only thing I am still missing is the TOC which
stays and easy access to search;-) , ala TurboGears
:http://www.turbogears.org/2.1/docs/modules/thirdparty/webob.html#webob.acceptparse.Accept
Werner
Andrea Gavana
I never managed to understand what the heck they are doing in this file:
As that mix of html, javascript and other things looks like a mix of
Chinese and Greek to me. I have tried to blindly adapt their
layout.html to the Phoenix one, but the end result was that the search
bar just disappeared... :-(
werner
On 29/02/2012 12:39, Andrea Gavana wrote:
...
> I never managed to understand what the heck they are doing in this
> file:
> http://sourceforge.net/p/turbogears2/tg2docs/ci/2ce485b956e55fc6237241c8c8659ebd785df44a/tree/docs/tgtheme/layout.html
> As that mix of html, javascript and other things looks like a mix of
> Chinese and Greek to me.
Same here.
> I have tried to blindly adapt their layout.html to the Phoenix one,
> but the end result was that the search bar just disappeared... :-(
> Andrea. "Imagination Is The Only Weapon In The War Against Reality."
> http://xoomer.alice.it/infinity77/
I had a similar approach, i.e. did it blindly, when I did some tests
with Sphinx and docs for MediaLocker.
Result:
http://thewinecellarbook.com/medialocker/mlsrc.mediaLocker.MediaLocker.html
I'll attach the theme folder for the above, maybe this helps.
Don't spend tons of time on this as it seems that I am the only one who
cares about this, if I find some time I might have a go at it myself.
Werner
Robin Dunn
Yes, that seems like a good approach.
Andrea Gavana
I have uploaded a new version of the Phoenix documentation, up to date
to today with the various new wx.ToolBar, wx.DateTime and friends and
wx.FileSystem and friends, plus their overview.
But what I wanted to say is: since we are already handling various
snippet of code, which then get embedded in the Sphinx output like
this:
http://xoomer.virgilio.it/infinity77/Phoenix/DateTime.html#DateTime.ConvertYearToBC
I would like to ask the community to try and contribute snippets of
code for methods/classes/functions which do not currently have a
wxPython example, and not to rely only on the translated C++ snippets
from wxWidgets. My point is, each of us has some nice trick in the
hat, short snippets that demonstrate the use of some methods/functions
in a smart or innovative way or simply they fully convey the
usefulness of a method. The snippets need not be full runnable
samples, just few lines of code showing how to call a specific method
(and maybe a comment).
If the community thinks that this is a reasonable idea and if someone
wishes to contribute something like this (and it can be an example of
use of any method/function/class in the Phoenix namespace), please do
send it to me. Normally the convention is to name the snippet of code
like "classname.methodname.INTEGER.py", i.e. if I want to contribute 2
snippets about the wx.CheckBox SetValue method, I'll call my Python
snippet files like this:
CheckBox.SetValue.1.py
CheckBox.SetValue.2.py
I believe it's worth the effort, but then again this is just my 2 cents :-)
Robin Dunn
> But what I wanted to say is: since we are already handling various
> snippet of code, which then get embedded in the Sphinx output like
> this:
>
> http://xoomer.virgilio.it/infinity77/Phoenix/DateTime.html#DateTime.ConvertYearToBC
>
> I would like to ask the community to try and contribute snippets of
> code for methods/classes/functions which do not currently have a
> wxPython example, and not to rely only on the translated C++ snippets
> from wxWidgets. My point is, each of us has some nice trick in the
> hat, short snippets that demonstrate the use of some methods/functions
> in a smart or innovative way or simply they fully convey the
> usefulness of a method. The snippets need not be full runnable
> samples, just few lines of code showing how to call a specific method
> (and maybe a comment).
>
> If the community thinks that this is a reasonable idea and if someone
> wishes to contribute something like this (and it can be an example of
> use of any method/function/class in the Phoenix namespace), please do
> send it to me. Normally the convention is to name the snippet of code
> like "classname.methodname.INTEGER.py", i.e. if I want to contribute 2
> snippets about the wx.CheckBox SetValue method, I'll call my Python
> snippet files like this:
>
> CheckBox.SetValue.1.py
> CheckBox.SetValue.2.py
>
> I believe it's worth the effort, but then again this is just my 2 cents :-)
+1 Please do help out where you can. To help get an idea of what
Andrea is asking for the existing snippets can be seen at the following
location in the source repository. They are just simple bits of code
that get merged in to the docs when they are generated.
Chris Barker
> On 3/12/12 3:28 PM, Andrea Gavana wrote:
>> I would like to ask the community to try and contribute snippets of
>> code for methods/classes/functions which do not currently have a
>> wxPython example,
> To help get an idea of what Andrea is
> asking for the existing snippets can be seen at the following location in
> the source repository. They are just simple bits of code that get merged in
> to the docs when they are generated.
I've got quite a few (~100 now!) small demo samples. For the most
part, the each:
are a complete app (al la "making sample apps")
demonstrate/test a single widget or concept.
But they are a fair bit larger than the snippets we're talking about here.
I have written them over the years from a combination of trying
out/testing stuff for myself, and answering questions for folks on the
wxPython list.
I've been looking for a while for a good place to put them, so others
can make use of them, and also test and improve them -- they certainly
need testing/updated with more recent wxPython (modification dates
back to 2008, and some may well be older)
So: should I see if I can figure out a way to re-organise these so
they could get built into the Sphinx docs? That would be pretty cool.
--
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
Robin Dunn
> On Mon, Mar 12, 2012 at 3:42 PM, Robin Dunn<ro...@alldunn.com> wrote:
>> On 3/12/12 3:28 PM, Andrea Gavana wrote:
>
>>> I would like to ask the community to try and contribute snippets of
>>> code for methods/classes/functions which do not currently have a
>>> wxPython example,
>
>> To help get an idea of what Andrea is
>> asking for the existing snippets can be seen at the following location in
>> the source repository. They are just simple bits of code that get merged in
>> to the docs when they are generated.
>
> I've got quite a few (~100 now!) small demo samples. For the most
> part, the each:
>
> are a complete app (al la "making sample apps")
>
> demonstrate/test a single widget or concept.
>
> But they are a fair bit larger than the snippets we're talking about here.
>
> I have written them over the years from a combination of trying
> out/testing stuff for myself, and answering questions for folks on the
> wxPython list.
>
> I've been looking for a while for a good place to put them, so others
> can make use of them, and also test and improve them -- they certainly
> need testing/updated with more recent wxPython (modification dates
> back to 2008, and some may well be older)
>
> So: should I see if I can figure out a way to re-organise these so
> they could get built into the Sphinx docs? That would be pretty cool.
Maybe they could be kept as standalone runnable samples and placed in a
separate area of the documentation. They could then be browsed as a
group and the user can select the one they want to look at from there,
and they can also be linked to from the specific class documentation
page for the widget that they demo.
Andrea Gavana
+1. If Chris can somehow "rename" his Python scripts to make my life
easier in linking them against a specific widget, it would be even
better. And it would be perfect if the samples had a few lines of
comment at the top so that I could extract those comments to make a
header description of the sample and then include the code as a Sphinx
Python output :-)