Re: Inconsistency in online docs
Lenard Lindstrom <len-l@...
2011-03-01 18:57:25 GMT
The .doc files are not actually Microsoft Word documents, but a custom
text based format for Pygame. The HTML is then generated with the
makeref.py tool, which is part of the Pygame source. To download the
source, and documents:
svn co svn://seul.org/svn/pygame/trunk
Each module's document file is found in the same directory as its
source. Any patches can be sent to this mailing list.
As to why Pygame and Pixelarray are swapped, I guess the index in
index.html is not updated automatically by makeref.py. The page needs to
be edited by hand. I will look at it.
On 01/03/11 10:30 AM, David Burton wrote:
> 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 <http://www.pygame.org/docs/>. (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.)
> On Tue, Mar 1, 2011 at 12:44 PM, Lenard Lindstrom <len-l@...
> <mailto:len-l@...>> wrote:
> 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
> On Tue, Mar 1, 2011 at 10:23 AM, Marcel Rodrigues
> <marcelgmr@... <mailto:marcelgmr@...>
> 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
> The issue was exposed in the IRC channel a few days ago, but
> apparently there was no person available to discuss.