[pygame] Inconsistency in online docs
At the top of the page in http://www.pygame.org/docs/ there are a list of links to module docs. I just noticed that this list is lacking links to Camera and Midi modules. These two modules are properly linked from any other module page (e.g. /docs/ref/color.html ), but not from /docs/ . Also, the links to Pygame and Pixelarray modules in /docs/ are alphabetically swapped. The issue was exposed in the IRC channel a few days ago, but apparently there was no person available to discuss. Marcel
Re: [pygame] Inconsistency in online docs
There are many other errors in the docs, too. Click show all comments and read the comments on the various documentation pages to read about them. They don't appear to have been updated in a long time. Is anyone in charge of those documents? Is there a way to volunteer to fix some of the problems? Alternately, could they be converted to a wiki, so that we could *all* fix them? Really, that seems to me like the best solution. Dave On Tue, Mar 1, 2011 at 10:23 AM, Marcel Rodrigues marcel...@gmail.comwrote: At the top of the page in http://www.pygame.org/docs/ there are a list of links to module docs. I just noticed that this list is lacking links to Camera and Midi modules. These two modules are properly linked from any other module page (e.g. /docs/ref/color.html ), but not from /docs/ . Also, the links to Pygame and Pixelarray modules in /docs/ are alphabetically swapped. The issue was exposed in the IRC channel a few days ago, but apparently there was no person available to discuss. Marcel
Re: [pygame] Inconsistency in online docs
Hi, I guess it is not a well advertised feature, but more recent docs are installed with Pygame. Try: python -m pygame.docs (or python -m pygamd.docs.__main__for python 2.6) This should bring up the local copy in a browser. If not, they are found in site-packages/pygame/docs But yes, the docs are incomplete and inconsistent. (It is more fun writing code. :-) ) The HTML is compiled from .doc files stored in the lib and src subdirectories in SVN. Anyone is welcome to download a copy, edit them, and submit patches to the mailing list. Updating the docs in SVN is on the TODO list. Personally, I am considering translating them to reStructuredText or something. Finally, the online docs are out-of-date. I believe there was a plan to have them update from SVN automatically. But I don't know what has happened to that. Lenard Lindstrom On 01/03/11 09:17 AM, David Burton wrote: There are many other errors in the docs, too. Click show all comments and read the comments on the various documentation pages to read about them. They don't appear to have been updated in a long time. Is anyone in charge of those documents? Is there a way to volunteer to fix some of the problems? Alternately, could they be converted to a wiki, so that we could _all_ fix them? Really, that seems to me like the best solution. Dave On Tue, Mar 1, 2011 at 10:23 AM, Marcel Rodrigues marcel...@gmail.com mailto:marcel...@gmail.com wrote: At the top of the page in http://www.pygame.org/docs/ there are a list of links to module docs. I just noticed that this list is lacking links to Camera and Midi modules. These two modules are properly linked from any other module page (e.g. /docs/ref/color.html ), but not from /docs/ . Also, the links to Pygame and Pixelarray modules in /docs/ are alphabetically swapped. The issue was exposed in the IRC channel a few days ago, but apparently there was no person available to discuss. Marcel
Re: [pygame] Inconsistency in online docs
Hi, Am 01.03.2011 18:44, schrieb Lenard Lindstrom: Personally, I am considering translating them to reStructuredText or something. That's exactly what I did quite a while ago: https://bitbucket.org/schlangen/pygame-docs/ The aim was to include it here: http://pygameweb.no-ip.org/docs/ (Of course there are no comments either, etc.) I had no time (and motivation) to update and improve the rst docs, but if you like it feel free to use it as starting point. Am 01.03.2011 19:30, schrieb David Burton: What's the download location for the .doc files, from which the .html is compiled, and to which mailing list should improvements be submitted? The .doc files come with python source code (see pygame website - download), the mailing list is this one. Also, what is used to compile those .doc files? I _like_ it! I've never seen such nice, simple, clean HTML come from a Microsoft Word document!! When Word, itself, generates the html from a .doc file (or when OpenOffice Writer or Wordpad does), the result is an ugly mess. It's no Microsoft Word at all. The .doc files are simple text files with some own very simple markup format. You can open and edit them with an text editor (unfortunately there is no documentation about the format, imo). There is a convertscript (makeref.py, basic html skeleton, style and everything is hardcoded there) to gererate .html from .doc files. (I once rewrote that to generate rst from the .doc files). Regards, Julian
Re: [pygame] Inconsistency in online docs
Hi Julian, Thanks, I will use you documents as a guide. Actually I was going to format the documents for Sphinx, like with pgreloaded, but now see that *is* reStructuredText. I intended to use a modified makeref.py to do the initial translation, then go from there. The one downside in switching formats is that additional packages will be required. Right now, everything needed to generate the html is included with the Pygame source. Lenard Lindstrom On 01/03/11 10:58 AM, jug wrote: Hi, Am 01.03.2011 18:44, schrieb Lenard Lindstrom: Personally, I am considering translating them to reStructuredText or something. That's exactly what I did quite a while ago: https://bitbucket.org/schlangen/pygame-docs/ The aim was to include it here: http://pygameweb.no-ip.org/docs/ (Of course there are no comments either, etc.) I had no time (and motivation) to update and improve the rst docs, but if you like it feel free to use it as starting point.
