Hi everyone,
I finally have a proposal for the reST file format for Pygame. I used
the following criterion:
1) Use only standard Sphinx markup so the source documents can be
processed without the Pygame Sphinx extensions and theme.
2) Accommodate Sphinx autodoc, which generates documents from Python
docstrings.
The new reST is more verbose that the first version, since it moves the
call signatures into a definition's body. But this lets Sphinx autodoc
extract them from the docstring rather than use introspection on the
callable itself, which is useless for extension module methods.
The generated HTML still needs some tweaking, but is close to a final
product. Don't worry that it retains the Classic look. It relies heavily
on stylesheets. Also criterion 1 above allows the standard Sphinx build
system to be used. So multiple versions of the documents can easily be
supported.
The reST files and resulting html documents can be downloaded from SVN:
svn co svn://seul.org/svn/pygame/branches/reStructuredText
What is left to do is generate a better index.html and incorporate the
tutorials and other companion pages.
For the Pygame documents, a longer term goal is to standardize the
documenting of call signatures. Other parts could also be made more
consistent. Using the Python guidelines (
http://docs.python.org/documenting/index.html ) should help here. It is
unclear whether this changes should be made to the current Pygame .doc
files for wait for the move to Sphinx (Is this definite now?).
Lenard Lindstrom