Re: [pygame] Using reStructuredText for document sources

[Peter Shinners <pete@xxxxxxxxxxxx>]

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 clear and obvious 
better solution.

Back when I created these files, we had ReST, but I found its syntax too 
verbose for comfort. Back then there also wasn't a project like Sphinx 
that could turn ReST documents into something usable on the web.

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 extension source. One big missing feature is that reference 
docs do not pull docstrings from of the .py files, which was always desired.


On 03/03/2011 03: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, document 
> generators are available off-the-shelf. So I am proposing to convert 
> Pygame's custom .doc files to reSTructuredText, and have docutils and 
> Sphinx generate the documents. As well as being the tool chain used to 
> produce the Python documents, Marcus uses reST for pgreloaded. Also, 
> Julian (jug) has translated the Pygame doc source to reST once 
> already. But I admit I did not fully appreciated his efforts at the time.
>
> I am already improving the makeref.py tokenizer for use in a Pygame 
> DOC to reST translator. Julian already wrote a makeref.py based 
> translator. I hope to using his reST version of the Pygame doc sources 
> as a guide for a translator that produces reST files closer to the 
> final product. If nothing else, makeref.py will generate somewhat 
> cleaner web pages.
>
> Before going any further I need to know what to keep from the current 
> Pygame document layout, what should change, and what can be added. I 
> suppose this has been discussed before, but I kind of missed it. Also, 
> if there are objections to moving to reST now is the time to raise them.
>
> Lenard Lindstrom