Re: [pygame] Inconsistency in online docs
(there are two big threads, so this might have been covered) 1] Is there a method other projects use, that we could copy? 2] I would definitely push for a web wiki-interface (at least to allow 'comment's section of current docs ) * allows correction submitions ( mentioned in other thread ) * would allow a more impromptu system for new updates -- vs same guy X always gets callled on. * allows easier to organize bite sized updates. (current is too much for one person, ie: could be: module X needs 3 edited docstrings) But first the existing docs have to be sorted out. 3] I'm willing to volunteer some work on the docs. but I'm not clear on what needs to be done. something like: a] first decide on long-term structure b] convert all docs to reST c] wiki interface 4] How much (or not) is the website and code integrated? I saw big threads about about redesigning the site, is that going on currently?
Re: [pygame] Inconsistency in online docs
Why not use a doc-generater? It sounds like the current method you have to write the docstring twice. ( or at least decreases ease to update ) -- Jake
Re: [pygame] Inconsistency in online docs
Hi Jake, Pygame does have a document generator, but it is tucked away in an obscured directory and only processes Python files. Sphinx also comes with a document generator. But first we would have to convert all the doc strings to reST markup. Also, how would a doc generator handle module level constants. These have no doc strings. I suppose they could be mentioned in the module header. It's something to look at in the long term. But first the existing docs have to be sorted out. Lenard Lindstrom On 30/03/11 02:00 AM, Jake b wrote: Why not use a doc-generater? It sounds like the current method you have to write the docstring twice. ( or at least decreases ease to update )
Re: [pygame] Inconsistency in online docs
Hi, those two modules are experimental in the current 1.9.1 release. cheers, On Tue, Mar 1, 2011 at 3:23 PM, 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
[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.