Pygame, python game developers and users

David Burton | 1 Mar 2011 18:17

Re: 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 <marcelgmr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> 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

headers

Lenard Lindstrom | 1 Mar 2011 18:44

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

headers

David Burton | 1 Mar 2011 19:30

Re: Inconsistency in online docs

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-EynCeXvFgoheoWH0uzbU5w@public.gmane.org> 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-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org <mailto:marcelgmr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>> 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

headers

Lenard Lindstrom | 1 Mar 2011 19:57

Re: Inconsistency in online docs

Hi David,

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.

Lenard Lindstrom

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.)
>
> Dave
>
>
> On Tue, Mar 1, 2011 at 12:44 PM, Lenard Lindstrom <len-l@... 
> <mailto:len-l@...>> 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@... <mailto:marcelgmr@...>
>         <mailto:marcelgmr@...
<mailto:marcelgmr@...>>> 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
>
>

headers

Lenard Lindstrom | 1 Mar 2011 21:20

Re: Inconsistency in online docs

I have seen problems with Internet Explorer, especially with spaces in 
the path (though there are none here). I guess I didn't fix everything.

Lenard

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.
>
[snip]
>
>
> On Tue, Mar 1, 2011 at 12:44 PM, Lenard Lindstrom <len-l@... 
> <mailto:len-l@...>> 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
>

headers

jug | 1 Mar 2011 19:58

Re: 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

headers

Lenard Lindstrom | 1 Mar 2011 20:50

Re: 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.
>
>

headers

Jake b | 30 Mar 2011 11:00

Re: 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

headers

Lenard Lindstrom | 30 Mar 2011 19:12

Re: 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 )
>
>

headers

Jake b | 31 Mar 2011 08:09

Re: 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?