On Tuesday 22 December 2009 23:40:43 Edwin Marshall wrote: > One thing that always concerned me about PyQt was that it's documentation > was pulled directly from the C++ documentation. Having looked at some of > the documentation in PySide, it seems as though the same style is being > followed. For example, I recently was having trouble getting the animation > framework examples to run until I was told that I needed to wrap arguments > inside of QVariants (which is not documented). Would I be right to assume > that the documentation itself won't become more pythonic until PySide > itself begins to become more pythonic? > > I think you all are doing a fantastic job with PySide, it is just sometimes > frustrating as a novice programmer to run into gotchas because certain > things aren't blatantly obvious in the documentation (assuming a lower > level of experience like I have). >
Yes, we know how frustrating it is, but did you notice how big is the Qt documentation? So rewrite the entire Qt documentation for PySide is not an option, at least not for me. But we need the documentation for PySide free of any C++ terms, i.e. a PySide reference, not a Qt/C++ one, this is a fact. The better way to fix it is adding "inject-documentation" and "modify- documentation" tags[1] in the typesystem where the documentation need to be changed. We can do it when someone report a problem, because search the entire documentation for all C++ stuff that needs to be replaced is so time consuming... so would be even better if the problem were reported with the proposed solution like: "Remove the 5th paragraph from the docs of method X of class Y, it doesn't makes sense for Python" or "Would be better if the text X were replaced by this text Y". Would be even more wonderful if instead of simple a bug report about the documentation, we find a nice patch for the typesystem with the desired changes just waiting to be reviewed and merged into :-D. Talking with Renato some weeks ago we had an idea for a huge improvement in the generated documentation, nowadays we don't insert the documentation into the PySide modules (__doc__ attributes), because this will increase the module size, loading time, memory footprint, etc... so, we can't generate the docs using the python tools for this job, the result is simple, more C++ noise into the PySide docs. The idea is to generate a version of the bindings with built- in docs just for documentation generation purposes. This is not hard to do, and the implications are nice, better documentation and turn docgenerator obsolete. [1] http://www.pyside.org/docs/apiextractor/typesystem_documentation.html > ____________________________________________________________ > GET FREE 5GB EMAIL - Check out spam free email with many cool features! > Visit http://www.inbox.com/email to find out more! > _______________________________________________ > PySide mailing list > [email protected] > http://lists.openbossa.org/listinfo/pyside > -- Hugo Parente Lima "Precisamos de mais gênios humildes no mundo, hoje somos poucos!" JID: [email protected]
signature.asc
Description: This is a digitally signed message part.
_______________________________________________ PySide mailing list [email protected] http://lists.openbossa.org/listinfo/pyside
