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

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



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




--
Jake