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 <le...@telus.net> 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 > >
