Hello,
is it ok if I make modifications to the docs in trunk? Is your
conversion automated? Or should I do it on the rst versions of the docs?
cheers,
On Tue, Apr 5, 2011 at 7:24 PM, Lenard Lindstrom <len-l@xxxxxxxxx
<mailto:len-l@xxxxxxxxx>> wrote:
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
<http://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