[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: [pygame] Update on Sphinx version of Pygame docs



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 <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

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