Re: [pygame] Using reStructuredText for document sources

[Casey Duncan <casey@xxxxxxxxxxx>]

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 into the docs automagically.

- Sphinx has very nice index support.

- You can actually run code examples to verify them, though strictly-speaking this is not a sphinx or rst feature (it comes from doctest).

- You can generate both html and pdf docs from the same source.

- Creating links in the narrative docs to the applicable reference (e.g., a method) is very easy.

- It generates a static web site, but includes a javascript search engine.

-Casey

On Mar 3, 2011, at 3:41 PM, René Dudfield wrote:

> Hi,
> 
> What does it gain?
> 
> 
> On Thu, Mar 3, 2011 at 11:09 PM, Lenard Lindstrom <len-l@xxxxxxxxx> 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
> 
>