For this I really love stackoverflow.
The one reply from 2008 and one from 2011 can be the best ones on the page,
therefore they both show on the first level.
But it also works because there are many mods. And regular users can
down/upvote.
Maybe a docs wiki has a plugin similar to this.
On Fri,
great work!
On Tue, Mar 29, 2011 at 8:31 PM, Lenard Lindstrom wrote:
> I have added C header file generation. There are some issues with generated
> C macro names. Currently makeref.py and the Sphinx header writer I wrote
> derive the names from different sources in the original Pygame .doc file
I have added C header file generation. There are some issues with
generated C macro names. Currently makeref.py and the Sphinx header
writer I wrote derive the names from different sources in the original
Pygame .doc files. But I'm sure I can get around that.
Attached a report generated with t
Swell!
On Sat, Mar 5, 2011 at 5:40 PM, Lenard Lindstrom wrote:
> Hi,
>
> Now there are comparison tools to consider :-). I'm not trying to push
> anyone into a move to reST. It's just that I was planning to go through the
> docs and standardize things like function protocols. Then the thread ab
On Sat, Mar 5, 2011 at 4:41 AM, René Dudfield wrote:
> On Fri, Mar 4, 2011 at 6:42 PM, David Burton wrote:
>
>
>> Uh, what does "ACE" mean?
>>
>> Dave
>>
>>
> hey,
>
> It's a superlative like excellent or RAD. As in 'Monty python is bulk
> ace!'.
>
Swell! * ;-)*
Dave
Hi,
Now there are comparison tools to consider :-). I'm not trying to push
anyone into a move to reST. It's just that I was planning to go through
the docs and standardize things like function protocols. Then the thread
about user contributions to the docs came up, and I figured now would be
On Fri, Mar 4, 2011 at 6:42 PM, David Burton wrote:
>
> Uh, what does "ACE" mean?
>
> Dave
>
>
hey,
It's a superlative like excellent or RAD. As in 'Monty python is bulk
ace!'.
On Sat, Mar 5, 2011 at 7:00 AM, Peter Shinners wrote:
> [snip...]
> Doing a one time conversion from the current Pygame docs should be easy, it
> was always meant to be. One current feature is that function signatures and
> summaries are translated into header files that are built into the exten
I'll throw in my coins...
In my mind the pygame doc files were always meant to be a stepping stone
towards something nicer that would eventually come along. During this
time there's probably been something better, and Sphinx is probably the
most correct direction. But I don't think there is a
On Fri, Mar 4, 2011 at 12:52 PM, René Dudfield wrote:
> Hi,
>
> oops. I was supposed to go through and fix the documentation for the 1.9.2
> release. There's hundreds of comments, and it took me about a week of
> writing last time I did it. I didn't see myself having a week for doc
> writing
Hi,
oops. I was supposed to go through and fix the documentation for the 1.9.2
release. There's hundreds of comments, and it took me about a week of
writing last time I did it. I didn't see myself having a week for doc
writing before the last release, so we decided it would be done in the 1.9.2
Hi,
I guess the concern is that there is no one assigned with doing overall
maintenance of the documentation. Pygame is an informal operation.
Lenard
On 03/03/11 11:28 PM, David Burton wrote:
Here's a better example, from the same documentation page, a
correction submitted nearly two years
I don't know. There is an online reST demo page:
http://www.tele3.cz/jbar/rest/rest.html
And reST can be embedded in MoinMoin markup:
http://moinmo.in/ReStructuredText
But someone else will have to answer the question of embedding an online
editor in the Pygame website.
Lenard
On 04/03/11
On Thu, Mar 03, 2011 at 10:06:34PM -0800, Lenard Lindstrom wrote:
> One advantage with formal documentation is it can be kept synchronized
> with Python doc strings. The current Pygame doc system does this in a
> limited way. Hopefully a move to reST will encourage even greater
> coordination
Here's a better example, from the same documentation page, a correction
submitted nearly two years ago, still uncorrected in the formal docs:
*Surface.unmap_rgb*
*convert a mapped integer color value into a Color*
Surface.map_rgb(mapped_int): return Color
*May 27, 2009 2:45am - Anonymous*
Also,
*Oops!* I was obviously too hastly picking my example.
As Mr. Anonymous wrote in his next comment, back in 2007:
*May 16, 2007 9:15am - Anonymous*
Actually, on re-reading the method description, I realize
that the "dest" argument means the position to where the
source Surface should be copied
On Fri, Mar 4, 2011 at 12:49 AM, Lenard Lindstrom wrote:
> ... As for comments, they can be hidden. But some way is needed to flush
> them. Maybe comments should only be allowed for the frequently updated docs,
> with comments older than (let's say) six months automatically deleted.
>
>
*N
One advantage with formal documentation is it can be kept synchronized
with Python doc strings. The current Pygame doc system does this in a
limited way. Hopefully a move to reST will encourage even greater
coordination. How would this be done with a wiki? Only the author of a
new Pygame featur
Hi Julian,
If the current Pygame layout can be recreated from your reST then
updating them is a practical. But I am unsure that Python directives
will do everything we want. If existing directives can be embellished,
then great. But if the only way to alter an existing directive is to
derive
Some major features I enjoy in using Sphinx:
- Nice reference documentation can be generated from python source/doc strings,
but you can also create reference docs directly as well.
- Nice formatting and syntax highlighting of code examples. It's also easy to
insert code from python modules int
Agreed! There are, however, many choices to be made... like what wiki
system to use.
There are a *lot* of Wiki systems available. http://www.wikimatrix.org/ lists
129(!!) different wiki systems.
Here's a comparison of a few of them:
http://www.wikimatrix.org/compare/DokuWiki+MediaWiki+MoinMoin
> This is what I'm afraid of. I would be very disappointed if the
> existence of a wiki led people to believe that maintaining
> proper documentation was no longer required.
If I may jump in briefly, how exactly would this be a bad thing? If people feel
that it's no longer required, that probably
On Thu, Mar 3, 2011 at 9:37 PM, Greg Ewing wrote:
> As for downloadability, I think that it is possible to export wiki
>> content as downloadable HTML documentation,
>>
> But then you just get a dump of a wiki, not properly designed
> and written documentation.
>
Why would you expect that the wi
David Burton wrote:
My prediction is that the pygame wiki will, before long, become the /de
facto/ main documentation, because it will be the most complete
and up-to-date, and whatever other documentation we have will fall into
disuse.
This is what I'm afraid of. I would be very disappointed
Currently makeref.py is hard coded to add these descriptions. I expect
with reST it can be moved to a template. Then the descriptions can be
included, excluded, or become a pop-up as desired.
Lenard
On 03/03/11 05:30 PM, Greg Ewing wrote:
René Dudfield wrote:
It's a short description of the
Hi,
The online documents at the Pygame site are for the last formal release,
Pygame 1.9.1. More resent documents are included with the SVN builds.
But they still need work.
Lenard
On 03/03/11 04:01 PM, David Burton wrote:
I think just putting up a wiki with the documentation would be much
b
Hi,
I will check that the current page layout is supported. It is one reason
I am putting some effort into a .doc to .rst translator. I don't want to
start editing reST files only to find out later that docutils or Sphinx
doesn't support some feature we expect. One reason to move to reST is
m
No, it would take no work at all. Wikis on non-political/non-controversial
topics like this are pretty much self-maintaining, and need little or no
moderation. If someone puts up spam/stupid/wrong content, then someone
(anyone!) else fixes it.
Of course it would get spam, just like the "comments
René Dudfield wrote:
It's a short description of the function - not so much a long winded
one.
It's still *far* longer than I want to see *every* time
the function is so much as mentioned, though!
perhaps add a title attribute to the link (which would give the
description on hover over the l
David Burton wrote:
I think just putting up a wiki with the documentation would be much
better.
-1. Wikis are all very well, but I don't believe they are an
acceptable substitute for carefully written, well-organised
and downloadable documents.
A wiki in *addition* to the downloadable docs is
Hi,
A small note about images, and writing style for those... It would be good
to keep figures at the bottom of the text. So that they can be easily
ignored, or stripped out for any editors/interpreters that don't support
showing inline images. Also, keeping as much formatting out of the docs a
Hi Lenard,
when I wrote my convert script [1] I reached a point when I found it
easier to edit the output (rst files) manually instead of implementing
proper handling for all the special cases etc. So maybe it would be
better to take my rst-files and continue to improve them (fix last
markup
On Fri, Mar 4, 2011 at 12:04 AM, Greg Ewing wrote:
> Lenard Lindstrom wrote:
>
>> I am proposing to convert Pygame's custom .doc files to reSTructuredText,
>> and have docutils and Sphinx generate the documents.
>>
>
> +1
>
>
> I need to know what to keep from the current Pygame document layout,
Lenard Lindstrom wrote:
I am proposing to convert
Pygame's custom .doc files to reSTructuredText, and have docutils and
Sphinx generate the documents.
+1
I need to know what to keep from the current
Pygame document layout, what should change, and what can be added.
I think the current orga
I think just putting up a wiki with the documentation would be much better.
It would put an end forever to the need for you to update the
documentation and the complaints about it being out of date!
Dave
On Thu, Mar 3, 2011 at 6:09 PM, Lenard Lindstrom wrote:
> Hi everyone,
>
> It seems that
Hi,
What it would give us.
=
- a documented format (our custom format isn't widely known, even though
it's very simple).
- reSTructuredText can be converted into other formats.
I think just those two are probably worthwhile enough reasons to do it.
The other question to ask is,
Hi,
What does it gain?
On Thu, Mar 3, 2011 at 11:09 PM, Lenard Lindstrom wrote:
> Hi everyone,
>
> It seems that as useful as it has been makeref,py, the custom Pygame
> document generator, is showing its age. It makes little sense to continue
> maintaining makeref.py when other, more powerful
Hi everyone,
It seems that as useful as it has been makeref,py, the custom Pygame
document generator, is showing its age. It makes little sense to
continue maintaining makeref.py when other, more powerful, document
generators are available off-the-shelf. So I am proposing to convert
Pygame's
38 matches
Mail list logo
