Re: [pygame] Inconsistency in online docs

2011-03-31 Thread Jake b
(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

2011-03-30 Thread Jake b
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

2011-03-30 Thread Lenard Lindstrom

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

2011-03-02 Thread René Dudfield
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

2011-03-01 Thread Marcel Rodrigues
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

2011-03-01 Thread David Burton
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

2011-03-01 Thread Lenard Lindstrom

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

2011-03-01 Thread jug

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

2011-03-01 Thread Lenard Lindstrom

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.