Hi Jake,
I was new to reST as well when I started this project. One advantage to
using docutils/Sphinx is it simplifies generating different document
formats from a single reST source. I would hesitate having links to
external javascript files in the documents packaged with Pygame because
the docs are designed to be read offline. But that doesn't stop one from
having an online version with such external links. In fact, I hope
others will create versions of the Pygame documents besides the
"classic" version.
Lenard Lindstrom
On 13/04/11 11:54 PM, Jake b wrote:
As a newbie to reST I don't feel qualified to decide. Although I found
a few resources I thought I'd share:
for the html docs:
you might be interested in a javascript sites include, that add syntax
hilighting to code found in the page. This leaves the original code
clean of styling. It should work on user comments
For newbies to SVN.
I found TortoiseSVN client simple to use. Had the reST downloading in
a couple minutes.
http://tortoisesvn.net/downloads.html
for reST newbies:
http://matplotlib.sourceforge.net/sampledoc/
http://packages.python.org/an_example_pypi_project/sphinx.html#full-code-example
http://stackoverflow.com/questions/4547849/good-examples-of-python-docstrings-for-sphinx
( found above links from Stackoverflow )
On Tue, Apr 5, 2011 at 1: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
--
Jake