On Wed, Jul 29, 2009 at 11:55 AM, jug <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).
