Hi René,
Yes, go ahead and make changes to the .doc files in trunk. The
conversion to reST is still automated (makerst.py).
I feel it's time to move the Sphinx stuff into trunk. The final move to
reST source can be deferred as long as desired. The reST derived help
page (index.html) is now more like the current one, though some styling
needs to be done. We could have a trial period where .doc -> .rst ->
.html to see how the new xhtml formatting is received before making a
final commit to reST.
Lenard
On 09/05/11 10:09 AM, René Dudfield wrote:
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 <le...@telus.net
<mailto:le...@telus.net>> 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
