Hi Robin & All,
Yes. It is the way it is currently because I was lazy and wanted to be
able
to include large blocks of copy/pasted Python code in a hurry. The plan
has
been to go back and turn at least some of those into extractor objects
like
PyMethodDef (or similar for standalone functions) so you can have
attributes
like function/method name, args string, docstring and body. That should
give you what you need for being able to generate the docs for those
items.
Thank you for that, I have integrated your methodology and you can see
the results in the newly uploaded docs.
I saw the CallLater class (and see how bare it looks without good
docstrings!) but I don't see the CallAfter function on the functions page.
http://xoomer.virgilio.it/infinity77/Phoenix/functions.html
Thanks, I had forgot to write down the docstrings. Fixed now.
I am surely forgetting something at the moment but I'll write to you
privately if anything comes to my mind.
It looks like you are not doing anything about overloaded functions,
methods
or constructors yet. In case you haven't seen it the extractor objects
for
functions and methods have an "overloads" attribute that is a list of
other
functions/method objects that have the same name. For example
Window.SetSize has 4 overloads:
SetSize\(x, y, width, height, sizeFlags=SIZE\_AUTO\)
SetSize\(rect\)
SetSize\(size\)
SetSize\(width, height\)
but it appears that only the first one is showing up in the docs
currently.
If you have a better idea of how to deal with this feel free to go that
way,
but the idea that pops into my mind is to group them all together in a
single block under the method signature ("SetSize(self, *args, **kw)" in
this example) and then for each of the overloads write the description,
parameters, notes or etc. and then after all the overloads put the things
that apply to all such as the "See also" section.
I think I have managed to get this issue solved in an acceptable
state, but please let me know if you see anything strange about my
implementation. There are a few instances where it seems that the
overloaded methods are a bit wrong, see for example:
http://xoomer.virgilio.it/infinity77/Phoenix/RadioBox.html#RadioBox
The constructor is described as:
__init__(self)
But then there is a bunch of parameters description below it... I am
not sure if it is a bug in my code (highly probable) or an issue in
yours (less probable).
It looks like that is coming from an overloaded constructor that has been
ignored. The ETG script has this:
c.find('wxRadioBox').findOverload('wxString choices').ignore()
so the C++ overload that takes a count and a plain C array will be ignored
and not wrapped. (We use the overload that takes a wxArrayString instead
because there is a %MappedType defined that will automatically convert a
Python list of strings to a wxArrayString.)
I don't see anything that might be clobbering those nodes, and the
sip_generator seems to be doing the right things there. Maybe you are not
checking the ignored flag everyplace it should be?
Thank you, that was the right suggestion. I wasn't checking the
ignored flag indeed, it should be fixed now.
Also, I noticed that there is not an entry for either of the Create methods
in the RadioBox page. Again one of them is ignored and the other is tweaked
a little just like the constructors.
This is because you are setting the "ignored" flag to True for the
main method (i.e., the one which has the overloads as children). This
requires a huge workaround to make the docstrings generation work, and
I haven't actually finished implementing it. It is the only issue
remaining on your list that hasn't been fixed.
To explain it better, I print this out from my generateClass method
(for wx.RadioBox):
for meth in klass:
if isinstance(meth, methods):
print meth.name, meth.ignored, len(meth.overloads) > 0
And I get this:
Method Name Ignored Has_Overloads
wxRadioBox False True
~wxRadioBox False False
Create True True <----
Enable False False
FindString False False
GetColumnCount False False
GetItemFromPoint False False
GetItemHelpText False False
GetItemToolTip False False
GetRowCount False False
IsItemEnabled False False
IsItemShown False False
SetItemHelpText False False
SetItemToolTip False False
Show False False
GetCount False False
GetString False False
SetString False False
SetSelection False False
GetSelection False False
GetItemLabel False False
SetItemLabel False False
As you can see, the main Create method has overloads but it is marked
as ignored. This is a nono at the moment. Put it in another way, the
main method should never have the ignored flag set to true if any of
its single overloads should not be ignored.
Let's assume that Create has 3 overloads. 1 should not be ignored, the
other 2 should be ignored. Then, irrespectively of their order in the
XML docs, the one that should not be ignored needs to be the main one
and the other two should go into the "overloads" list as "children" of
the main one.
I can probably work around this thing but I believe it should be
handled by the original sip/pi/whatever generators/extractors stuff.
The documentation is now much more complete, with Window styles/extra
styles, event processing, return type for some of the
methods/functions and also a few more hidden goodies 
Please let me know if you see anything strange.
* It looks like there are some cases of overloaded methods sharing a single
(or identical) docstring. See wx.Colour.Set for example. If you're able to
detect that situation then it would be nice to write the text for that
method appropriately, perhaps list each of the method signatures and
parameter lists first, and then write the text just once after that.
Done. There is stil some space optimization to be done there, for
example: do all the overloaded methods have *always* the same return
type? If this is the case, I could put the return type at the end of
the description.
* Are you doing anything about output parameters yet? It looks like they
are just being ignored currently, see the wx.ClientDisplayRect function for
example. It would be nice to have the normal "Return type: tuple" and
"Returns:" section for it. My preference would be to list the parameter
names there, like "(x, y, width, height)". Keep in mind that if the C++
function has a return value as well as output parameters then the return
value will be the first item in the tuple. There are also some cases of
parameters that are marked as both input and output, such as in
wx.Colour.ChangeLightness.
I've got some code in extractors.FunctionDef.makePyArgsString that I use to
build a string showing the parameters and return value(s) that you can
probably borrow some code from. (And if your generator is being run after
the sip_generator then that string should already be in the .pyArgsString
attribute of function and method nodes.)
The "return" stuff was just incomplete up to yesterday. I have tweaked
it and now you should see a much better representation of what you
were expecting.
* I'd like to do something different about the enums, but I'm not sure what
yet...
I have seen your other message about the enum, I'll implement it by
Monday, it should be relatively easy. Do you still want the "Note"
inside the widgets classes referring to the enum or not?
* For PyMethodDefs where the .deprecated attribute is true I would be
inclined to just leave them out of the docs. In most cases they are only
there for backwards compatibility and are very simple wrappers around some
other method that is documented. I expect that there can always be
exceptions to this rule so maybe they should be omitted unless the briefDoc
or detailedDoc attributes are set.
Done.
And I've got a few (hopefully) minor usability and style requests:
* Can we use the big Phoenix + wxPython image only on the "Home" and main
"Documentation" pages of the docs and not on the rest of the pages?
Not directly via Sphinx, I made it work by (automatically)
post-processing the HTML files generated by Sphinx.
* When clicking on a cross-reference link to a class, say Size, the URI
jumped to is .../Size.html#Size and the additional anchor takes you to the
"class Size" in the "Class API" section. Can we instead have them just go
to the top of the page instead? I expect that most of the time people are
going to be more interested in seeing the class description or other items
at the top of the page to start with.
That was a hard one, and the fix is a terrible hack. The reason why
the URI jumped to the class definition is because I was using the very
convenient Sphinx :class: role. I had to switch back to the :ref:
role, but this has a couple of disadvantages:
1) :class: doesn't complain when it doesn't find a valid class
definition (i.e., :class:Grid doesn't emit a warning, :ref:Grid does),
and there are many, many classes not yet wrapped (and there will be
some that will never be wrapped in wxPython, as they are purely C++
classes for which the Python lib already provides good alternatives).
This means that my clean, beautiful Sphinx build went from 3 harmless
warnings to 444 missing ":ref:" when built.
2) The :ref: trick above can be applied only for inline docs and
return types, not to parameters, because in ReST you can not write
this:
:param :ref:`GCDC` `hello`: some description
As the :param: roles uses the ":" to correctly generate the HTML docs.
If you write this:
:param `GCDC` `hello`: some description
Then you get the correct HTML stuff *but* clicking on the GCDC link
will bring you to the class definition, not to the top of the page.
The only solution to this is to post-process the HTML docs, which I
did and which is a terrible, terrible hack.
* In the Events tables there is some stock text generated by a doxygen macro
that looks like "The following event handler macros redirect the events to
member function handlers 'func' with prototypes like:..." and then it shows
a code snippet of what the C++ event handler method should look like. IMO
the only important part of that is what is the type of the event object
passed to the handler. So for it to make more sense for Python people I'd
like to change all of those to something like, "Handlers bound for the
following event types will receive a CommandEvent parameter." (Using the
correct event class type of course.)
Done.
* In the Events tables we should drop the "(id, func)" after the EVT_ items,
or anything else that may appear in ()'s there. They are almost never used
as callable objects anymore in wxPython.
Done.
* Let's change "Events Processing" to "Events emitted by this class"
Done, although you forgot to capitalize the sentence (Events Emitted
by this Class)
On a completely unrelated note, I got (yet another) message telling me
that some internet security firm (!), M86 or similar, has black-listed
the xoomer*.*it domain and it appears quite a few people have problem
accessing the docs just to take a peek. Now, I have tried to generate
a PDF file out of the docs to upload it somewhere for those people to
take a look, but rst2pdf is completely useless with Sphinx 1.X. I
could either:
1) Create a CHM and upload it somewhere;
2) Get a new domain and re-upload the docs. I am no web expert so I
welcome any suggestion for a free, free-of-trouble web space
somewhere.
Please let me know what you think and what still needs to be adjusted
in the docs.
Andrea.
"Imagination Is The Only Weapon In The War Against Reality."
http://xoomer.alice.it/infinity77/
···
On 16 December 2011 02:50, Robin Dunn wrote:
)