[PySide] PySide Documentation and Tutorials for beginners
João Ventura
is anyone here responsible for the documentation in the PySide wiki?
The reason is that PySide is reaching version 1.0 pretty soon, and i
think it should be better documented for newbies and beginners like
me. For instance, when i've decided to go with PySide for my projects
(about 3 weeks ago), i've started to search for pyside tutorials and
as i couldn't find much, i had to search for PyQt things. I've
followed some examples, but it has cost me too much time searching for
something to start. Now i have the problem of searching how to do
start working with qml and pyside. So, the same kind of things
happening twice is really bad.
So, the reasoning that i'm asking if there is a responsible for the
wiki Documentation is that i would like to contribute some things, but
i don't want to mess with other people's work. I have already written
a wiki page "Setting up PySide" (http://developer.qt.nokia.com/wiki/
Setting_up_PySide) with some basic information that took me almost 1
hour to search in the first time. And i would also like to reorganize
some things that has to do with tutorials for beginners, if everyone
agrees?!
The two main reasons that i want to contribute something is that i
believe that good documentation for beginners is essential for a
project like this, and because i am a beginner.
Thanks,
João Ventura
_______________________________________________
PySide mailing list
PyS...@lists.openbossa.org
http://lists.openbossa.org/listinfo/pyside
Matti Airas
I guess I made the initial wiki doc layout when migrating our existing
docs from the pyside.org website to the wiki. My hope was to encourage
participation in creating missing documentation (and maintaining
existing, of course). I've been happy to see people contribute quite a
bit of stuff there, but indeed, we're still woefully short on newbie
docs (despite e.g. some good initial efforts by Al Kabaila). Also, the
wiki doc organization is indeed quite bad. If you're interested in
working on them, that'd be just great!
A couple of practical remarks:
- When creating new pages, try to include "PySide" or "Python" in the
page name (we share the wiki with other Qt developers)
- Add any new pages to the PySide category by adding the following tag
to the top of the page: [[Category:LanguageBindings::PySide]]
- Currently, regular users can't rename pages on the wiki. If you need
to do that, copy the contents over to the new page, and then report the
old page to the admins (by pressing the Report button) for deletion.
They've been quite patient with my requests so far. :-)
Glad that you're willing to work on this!
Cheers,
ma.
P.S. Just noticed the PySide main wiki page [1] has already been
translated to Spanish, (Dirty?) Hungarian, and Italian. Wonder when we
get the Portuguese translation? ;-D
[1] http://developer.qt.nokia.com/wiki/Category:LanguageBindings::PySide
João Ventura
i've just started to contribute two wiki pages: How to set up PySide
(refering to downloads) and how to create a simple hello world. You
can check both on the Documentation and in http://developer.qt.nokia.com/wiki/Setting_up_PySide
and http://developer.qt.nokia.com/wiki/Hello_World_in_PySide
I've followed you suggestion about keeping PySide in the names and the
category markup! I seem to have encountered a problem, which is not
really a problem, but more of a feature. When i go through
Documentation to any other page, i see that that page is accessed
through "PySideDocumentation" but it is not son of
"PySideDocumentation". It think that "PySideDocumentation" should be
transformed into a category, and that anything under it should be
"sons" of that category. I tried to do it, i.e., i've created the
category but i can't redirect the wiki page "PySideDocumentation" to
the newly created "PySideDocumentation" category. The reason is that i
don't want to break existing links to the "PySideDocumentation" page.
Do you have any idea how to do it?
I won't try to do it by trial and error again, to not pollute the wiki
with "zombi" wiki pages.
Perhaps someone should plan the documentation structure. I propose
something like:
- Getting started
- how to set up PySide
- how to start using it
- how to make some simple things
- Tutorials
- Signals and Slots
- how to use it
- new types of signals
- ...
- Others things (which things? - i am merely a beginner)
- API reference
- etc..
Each of the "top" things, if it will have "sons" should be a category
instead of a page. Makes more easy to navigate in the wiki menus.. If
no one objects, and while time permits, i will be doing this..
Thanks,
João Ventura
> PyS...@lists.openbossa.orghttp://lists.openbossa.org/listinfo/pyside
Algis Kabaila
A structure in a wiki is a highly desirable feature. Like most
wiki's, the qt developer wiki has a "flat" file structure and
any attempt to structure it differently is by necessity shallow.
I am a great believer in the KISS principle. The semblance of
structure can be achieved very simply without messing up the
category system by giving references to the "children" pages
from a "main" page and the back references to the main page from
the children page.
A tiny start in that direction can be seen by going to
http://developer.qt.nokia.com/wiki/PySide_Newbie_Tutorials
and then visiting the children pages. If you find the approach
unsuitable, I would appreciate it if you air your concerns.
Negative but thoughtful cricisim is particularly appreciated.
Kind regards,
Al.
--
Algis
http://akabaila.pcug.org.au
Algis Kabaila
>
> i've just started to contribute two wiki pages: How to set up
> PySide (refering to downloads) and how to create a simple
> hello world.
I had a look at your page on prerequisites and the proverbial
"Hello World" and took the liberty to put some links to it in
the first "child" page in:
http://developer.qt.nokia.com/wiki/PySide_Newbie_Tutorials
If you care to look at it, you will find a simple implementation
of what seems to be a "parent" and "children" pages in a flat
file system of the wiki.
In addition, cross-referencing can also be useful IMHO.
Keep up the good work!
Al.
--
Algis
http://akabaila.pcug.org.au
João Ventura
i agree with you and also i like things simple. When someone is
searching for how to do something, most of the times that person is in
a hurry and doesn't care about the "bla bla bla" and just wants to
start coding. That's why i believe there must exist tutorials for real
beginners like that example of the Hello World.
But i think we should consider using the categories in the wiki,
because the wiki gives a kind of menu above the contents where the
user can "see" where he is, and it contextualizes things. See, for
example, this page http://developer.qt.nokia.com/wiki/Generating_new_bindings_with_PySide/
and you will see that it comes from a category called Shiboken which
is "son" of PySide category. I think that in some situations, your
approach (without categories) is more important, in other situations,
having the pages in categories is easy for the "navigation" in the
wiki. We just have to see where each one applies as things get done.
But, the parent-child approach i believe it is the best
Also, i pretend to structure today the documentation pages. It will
change to something like:
- Getting started
- Setting up
- Yout first PySide application
- Tutorials by experience level (Beginner, Intermediate, Advanced)
- Tutorials by category (Desktop, mobility and QtQuick/QML)
- API References
- Examples
- Bits and Pieces
- Diferences between PySide and PyQt
- PSEP's
- Building
- Generating Bindigs (will redirect to Shiboken)
The idea is to keep the pages really clean, usable and structured. I'm
in the mood for this, and will keep on doing until someone says it is
starting to look awful (hope not)! Will take in consideration the
ideas of Algis specially in the tutorial pages.
Algis, i will insert the simplissimus and your page where i think it
makes more sense, but if you agree with my changes and want to insert
the examples in other way, you're welcome. Strange, i have the feeling
that i've hijacked the wiki documentation. I'm pretty new around here,
so if someone does not agree with my "interference", please alert me
before i make any thing that the community doesn't agree!
Thanks,
João Ventura
On 19 Jan, 05:03, Algis Kabaila <akaba...@pcug.org.au> wrote:
> Hi João Ventura,
>
> A structure in a wiki is a highly desirable feature. Like most
> wiki's, the qt developer wiki has a "flat" file structure and
> any attempt to structure it differently is by necessity shallow.
>
> I am a great believer in the KISS principle. The semblance of
> structure can be achieved very simply without messing up the
> category system by giving references to the "children" pages
> from a "main" page and the back references to the main page from
> the children page.
>
> A tiny start in that direction can be seen by going to
>
> http://developer.qt.nokia.com/wiki/PySide_Newbie_Tutorials
>
> and then visiting the children pages. If you find the approach
> unsuitable, I would appreciate it if you air your concerns.
> Negative but thoughtful cricisim is particularly appreciated.
>
> Kind regards,
> Al.
João Ventura
I've just reorganized a lot of things on the Documentation wiki page,
created other pages to receive the information that was "loose" on the
Documentation, but i don't know if everything are in the right places.
If someone wants to check, please do. Btw, the documentation seems more
"cleaner" now, doesn't it?
Of course, this structure seems to fit for now but as more information
is hopefully added, maybe it will need to be reorganized again. But for
now, i believe it fullfils its purpose.
I don't know many things about "Generating new bindings". Does anyone
want to reorganize than little piece in the main documentation? I didn't
want to mess with something that i really really don't know. I suggest
something like creating a new wiki page and pass some information to
there with a introduction and something like that..
Now i need to start learning how to do something in PySide and
QtQuick/QML, like an Hello World.. There's not much information about
that, so i know it will take a couple of hours. That is the main reason
that i started doing the tutorials for beginners and restructuring
documentation: Nobody should take more than a couple of minutes to do a
"Hello World" app whatever technology is behind...
Hope everyone agrees with the structural changes in the wiki!
Thanks,
João Ventura
Matti Airas
> I've followed you suggestion about keeping PySide in the names and the
> category markup! I seem to have encountered a problem, which is not
> really a problem, but more of a feature. When i go through
> Documentation to any other page, i see that that page is accessed
> through "PySideDocumentation" but it is not son of
> "PySideDocumentation". It think that "PySideDocumentation" should be
> transformed into a category, and that anything under it should be
> "sons" of that category. I tried to do it, i.e., i've created the
> category but i can't redirect the wiki page "PySideDocumentation" to
> the newly created "PySideDocumentation" category. The reason is that i
> don't want to break existing links to the "PySideDocumentation" page.
> Do you have any idea how to do it?
Took a bit of digging, but the answer was near: the PySide page is a
redirection, and when you edit it, you get:
#REDIRECT [[Category:LanguageBindings::PySide]]
The idea to use categories to organize the contents is really good. One
small comment, though. For some reason, the practice seems to be to
separate the subcategories by two colons (see the example above). It
works more or less also with one, but you get different results that
way. So, better stick to double-colons.
ma.
Matti Airas
> Hi all,
>
> I've just reorganized a lot of things on the Documentation wiki page,
> created other pages to receive the information that was "loose" on the
> Documentation, but i don't know if everything are in the right places.
> If someone wants to check, please do. Btw, the documentation seems more
> "cleaner" now, doesn't it?
Yes, a lot!
One minor thing that stuck my eye: while it's really nice to have the
two separate pages for tutorials, I wonder won't they fall out-of-sync
really fast? Maybe it would be simpler to create a
Categories:LanguageBindings::PySide::Documentation::Tutorials category
and stuff them all there. I'd prefer to have them sorted by the
experience level.
> I don't know many things about "Generating new bindings". Does anyone
> want to reorganize than little piece in the main documentation? I didn't
> want to mess with something that i really really don't know. I suggest
> something like creating a new wiki page and pass some information to
> there with a introduction and something like that..
I guess they could be where they are for now. They're conceptually a bit
different than the rest of the stuff (somewhat different target
audiences and so on), and it might not make sense to mix the binding
generation tutorial with the others... or then again it might, depends
on your preferences, I guess. :-)
> Hope everyone agrees with the structural changes in the wiki!
Absolutely! Big thanks for the job you did!
ma.
João Ventura
On 19 Jan, 13:51, Matti Airas <matti.p.ai...@nokia.com> wrote:
> One minor thing that stuck my eye: while it's really nice to have the
> two separate pages for tutorials, I wonder won't they fall out-of-sync
> really fast? Maybe it would be simpler to create a
> Categories:LanguageBindings::PySide::Documentation::Tutorials category
> and stuff them all there. I'd prefer to have them sorted by the
> experience level.
You are right, I don't like it either, although i've done it. It think
i will follow your suggestion, regarding the categories.
I also prefer the separation by experience level, but people may need
to find basic information also for QtQuick/QML and PySide Mobility. Do
you think that each of these things (PySide, Mobility and QtQuick/QML)
should have its own category, and its own sub-documentation? It makes
sense for me, because it seems that, although they can be intertwined
(mix PySide and QML), they can have different examples, tutorials,
ideas, etc.. It is just a form of structure..
I re-propose to add wiki pages/categories about QtQuick/QML and
Mobility on the "Getting Started", and insert there the information
about how to use it, tutorials, examples, etc. What do you think about
that? We can always revert it back if we don't agree..
> > I don't know many things about "Generating new bindings". Does anyone
> > want to reorganize than little piece in the main documentation? I didn't
> > want to mess with something that i really really don't know. I suggest
> > something like creating a new wiki page and pass some information to
> > there with a introduction and something like that..
>
> I guess they could be where they are for now. They're conceptually a bit
> different than the rest of the stuff (somewhat different target
> audiences and so on), and it might not make sense to mix the binding
> generation tutorial with the others... or then again it might, depends
> on your preferences, I guess. :-)
Maybe creating a wiki page/category for those who handles with the
internals of PySide?
> > Hope everyone agrees with the structural changes in the wiki!
>
> Absolutely! Big thanks for the job you did!
>
> ma.
Will keeping on doing it..
Ah, about your suggestion of translating the wiki pages to portuguese,
it is feasible, just let the documentation stabilise. Here in
Portugal, almost everyone knows English beside Portuguese, and some
can talk even more than two languages, so it is not really a big
priority..
Regards,
João Ventura
Matti Airas
> Hello Matti Airas,
>
> On 19 Jan, 13:51, Matti Airas<matti.p.ai...@nokia.com> wrote:
>> One minor thing that stuck my eye: while it's really nice to have the
>> two separate pages for tutorials, I wonder won't they fall out-of-sync
>> really fast? Maybe it would be simpler to create a
>> Categories:LanguageBindings::PySide::Documentation::Tutorials category
>> and stuff them all there. I'd prefer to have them sorted by the
>> experience level.
>
> You are right, I don't like it either, although i've done it. It think
> i will follow your suggestion, regarding the categories.
>
> I also prefer the separation by experience level, but people may need
> to find basic information also for QtQuick/QML and PySide Mobility. Do
> you think that each of these things (PySide, Mobility and QtQuick/QML)
> should have its own category, and its own sub-documentation? It makes
> sense for me, because it seems that, although they can be intertwined
> (mix PySide and QML), they can have different examples, tutorials,
> ideas, etc.. It is just a form of structure..
It just occurred to me that since categories can be considered as tags
(you can have pages belonging in more than one category at the same
time), you can use categories to maintain the different tutorial levels
and tutorial topics. Or maybe that was already what you suggested?
> I re-propose to add wiki pages/categories about QtQuick/QML and
> Mobility on the "Getting Started", and insert there the information
> about how to use it, tutorials, examples, etc. What do you think about
> that? We can always revert it back if we don't agree..
Sure.
> Maybe creating a wiki page/category for those who handles with the
> internals of PySide?
Basically that's what the Shiboken category is already about. I wonder
should it rather be Categories:LanguageBindings::PySide::Shiboken
instead of Categories:LanguageBindings::Shiboken, though?
> Ah, about your suggestion of translating the wiki pages to portuguese,
> it is feasible, just let the documentation stabilise. Here in
> Portugal, almost everyone knows English beside Portuguese, and some
> can talk even more than two languages, so it is not really a big
> priority..
Nah, it was more of a quip at our rather numerous Portuguese-speaking
developers. :-) I agree that it's not a real priority.
ma.