On Wednesday 23 December 2009 02:50:47 Edwin Marshall wrote: > Makes sense. While I'm not adept enough of a programmer to correct all the > documentation that is still in C++ syntax, there are a few instances where > I know what the differences are. I will look at the API Extractor > documentation you linked to and, assuming it isn't too far over my head, > submit what changes I can. Hopefully, I will make some headway and it will > be a learning experience for me, as well as allow me to give back to such > a great project.
I guess that we, the PySide core developers should create a tutorial, something like "How to fix the documentation", because I don't know if the documentation is clear enough for a person without experience with our binding generator tools, but you could be a nice test! Just report your achievements and we'll try to guide you when/if you get stuck. > > -----Original Message----- > > From: [email protected] > > Sent: Wed, 23 Dec 2009 00:19:19 -0200 > > To: [email protected] > > Subject: Re: [PySide] Documentation > > > > 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] > -- 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
