Hi Brian,
Brian Fisher wrote:
On Wed, Jul 29, 2009 at 11:55 AM, jug <j...@fantasymail.de
<mailto:j...@fantasymail.de>> wrote:
Yeah, sorry. It uses simple text files with an own simple
structure and markup. So, it's not as bad as I thought. But still
bad. IMHO, bad enough to be replaced.
It *is* something self-made, the html and css is *hardcoded* into
the generator script and therefore it *is* impossible to change
easily. Finally, the output *is* ugly and *invalid*
(http://validator.w3.org/check?uri=http%3A%2F%2Fwww.pygame.org%2Fdocs%2Fref%2Fsurface.html).
However, after some trial and error and some changes on the
generator code, I got the docs integrated into the website (used
code from svn, so docs are for pygame 1.9.0):
http://pygameweb.no-ip.org/docs/
So, if no one is interested in a more professional documentation
system, we should at least update the generator script to produce
some more valid code, use a simple template for html and css and
become a bit more configurable.
Julian,
good job on working with current documentation content to get a
page working. However I have to say that I do not find this page:
http://pygameweb.no-ip.org/docs/
to be any improvement at all over this page:
http://www.pygame.org/docs/
I don't think the aesthetics or usability have been improved. But my
real critique of it is that you dropped what I considered to be a
highly effective and useful format for documentation - to have single
page docs for a module, where the top half of the page is functions
for the module that links down to the dull description later on the
same page.
The problem is that with your main page being a list of all modules
and their functions together, it's hard to get a good overview of the
modules compared to a list of each module with short descriptions.
Likewise, once I've decided a module is for me, and choose to go to
it's page to drill into it, I don't get a clear and simple overview of
that module.
I hope the doc pages are something you continue to improve from the
perspective of easily getting overviews of things and getting a high
level picture of what the library has to offer.
And lest you think I'm biased, I didn't do a single thing to work on
the current pygame website or doc system, and have no particular love
of the current website. I just happen to have had a really great
experience working with pygame's website doc pages over the years -
it's always been a lovely experience to browse them for me because
it's so easy to get a high level picture and find what I want. I find
them to be far more usable and effective than python's own doc web
pages, which are at times overwhelming and impossible to get a good
high level view from (like say the urllib & firends docs for instance
- where you don't even know what classes or modules you want to use,
and once you do have a guess at that, it's hard to find a useful
function).
Indeed, the docs at pygameweb are not better than the ones on pygame.org.
I just had a look into the generator script and modified it to produce
templates
I can use with the rest of the website (so that the recent-releases and
the menubar are still there). Then, its valid XHTML 1.0 Strict.
Surely it needs more improvements. I'll try to get the index page
clearer, for the rest, I don't know yet. Eg.
http://pygameweb.no-ip.org/docs/surface.html ist not really easy to
read, but I don't know exactly why.
Feel free to help improving it.