Re: [pygame] Inconsistency in online docs

[David Burton <ncdave4life@xxxxxxxxx>]

Thanks, Lenard.

However, those commands don't work for me with either python 2.6 or 3.1.  It fires up my web browser but just shows my home page.  But simply opening file:///C:/python31/Lib/site-packages/pygame/docs/index.html in a web browser works.

However, that version of the documenation is less useful than the online version, because it lacks the comments which pygame users have added in the online version.  (I didn't immediately notice any fixes, either; e.g., as Marcel noted, the links to Pygame and Pixelarray are still alphabetically swapped.)

What's the download location for the .doc files, from which the .html is compiled, and to which mailing list should improvements be submitted?

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.

(However, for pygame documentation I would still prefer a Wiki.)

Dave

On Tue, Mar 1, 2011 at 12:44 PM, Lenard Lindstrom <len-l@xxxxxxxxx> wrote:

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 <marcelgmr@xxxxxxxxx <mailto:marcelgmr@xxxxxxxxx>> 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