Re: [pygame] Using reStructuredText for document sources

[René Dudfield <renesd@xxxxxxxxx>]

On Fri, Mar 4, 2011 at 12:04 AM, Greg Ewing <greg.ewing@xxxxxxxxxxxxxxxx> 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, what should change, and what can be added.

I think the current organisation is mostly okay. The only
serious problem I've found is that a big long-winded description
of each function seems to get inserted everywhere there's a
link to that function. I'm hoping that's a bug that will
disappear in the transition!

--
Greg

hehe, that's not a bug ;)

It's a short description of the function - not so much a long winded one.  Mostly I think it's a #winner... especially for new users.  But it's also a little distracting.  However most pygame functions use fairly self descriptive variable names.  Probably good to take it out, and perhaps add a title attribute to the link (which would give the description on hover over the link).

cu.