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
