[pygame] Improving documentation

[jug <jug@xxxxxxxxxxxxxx>]

Hello!

Some months ago, there was a discussion about the documentation system
of pygame (and it's output), but without any results.

Some say its ugly (like the website), some say its a bit unclear, some 
may like it.
Some parts could definitively be improved.

Then, there is this comment system inside the documentation with some 
very useful
comments that are essential for understanding (ie. the docs are 
incomplete there)
but also lots of comments with spam, useless content or really large 
examples that
may be useful but should not belong to documentation (better in the wiki 
or pcr or
snippets section or so).

Another point is, that the documentation is not portable. You can only 
build the docs
as html pages in this ... green(?) style and without comments.

In the earlier discussion, Marcus made a case for Sphinx, a tool also 
used for the
python documentation. It has several advantages:

- Its a standardized tool that uses reStructuredText, an easy but 
powerful markup
 language known by many python'ists (-> easier for contributors)
- It generates several formats like html or pdf from plain text files. 
That also makes
 it easy to mix api documentation with with deeper explanations. 
- It supports some kind of theming, ie. you can use one of a few default 
styles or
 even write your own one and/or edit/extend the templates.
- It has a plugin system with some useful extensions

That's why I (and some others) think that porting pygame documentation 
to Sphinx
would be a good start to improve it. And thats what I did.

http://bitbucket.org/schlangen/pygame-docs

I've created a project on bitbucket, so everyone who'd like to 
participate can do that
easily.  I've already converted the docs to a Sphinx project, but it 
needs some manual
control and cleanup and then content improvements.

A small preview how it *could* look can be found here (using a default 
style - as I said, you
can change this style nearly completely):

http://pygameweb.no-ip.org/media2/newdoc/api/rect.html

(This page is manually converted, the other pages are build with a
modified version of makeref.py)


Regards,

   Julian