Commits

Anonymous committed cf97441

Rewrite of setup.py for cleaner doc build process; pygame api docs.

Comments (0)

Files changed (11)

doc/manual.txt

-
-:author: Alex Holkner
-:address: aholkner@cs.rmit.edu.au \\\\
-    http://www.pygame.org/ctypes
-
-:revision: 0.05
-:date:  4 July 2006
-
-:copyright: Copyright (c) 2006 Alex Holkner.
-
-==========
-SDL-ctypes
-==========
-
----------------------
-Introduction
----------------------
-
-SDL-ctypes is a wrapper module for the `Simple DirectMedia Layer`_ (SDL) and
-its companion libraries SDL_image, SDL_mixer and SDL_ttf.  
-
-Example programs ported from the SDL library are in the ``test`` directory.
-You can use SDL-ctypes to access all SDL functions and data types.
-Pixel and audio buffers can be manipulated using either slices or NumPy_.
-SDL can also provide a context for PyOpenGL_ to work with.
-
-.. _Simple DirectMedia Layer: http://www.libsdl.org
-.. _NumPy: http://numeric.scipy.org
-.. _PyOpenGL: http://pyopengl.sourceforge.net
-
-Versions
-========
-
-SDL-ctypes supports:
-
-    SDL
-        Versions 1.2.1 through 1.2.11
-    SDL_image
-        Unversioned release on 13 April 2002 through 1.2.5
-    SDL_mixer
-        Versions 1.2.6 through 1.2.7
-    SDL_ttf
-        Versions 2.0.7 through 2.0.8
-    SDL_sound   
-        Versions 1.0.0 through 1.0.1
-
-Note that earlier versions are not available through the SDL subversion
-repository.
-
-SDL-ctypes requires Python 2.4 or later.  On Mac OS X SDL-ctypes also requires
-PyObjC to be installed.
-
----------------------
-Usage
----------------------
-
-If you are familiar with SDL in C, you should find SDL-ctypes 
-to be fairly intuitive.  The interface has been kept as consistent as
-possible, while making it simple to use in Python.
-
-The following sections detail the general differences you can expect to
-see.
-
-Importing
-=========
-
-The preferred way to use SDL-ctypes is with::
-
-    from SDL import *
-
-This follows the convention of PyOpenGL, and allows you to call SDL
-functions in the same way as the C library.  The actual package is
-composed of several modules such as ``SDL.cdrom``, ``SDL.video``, and
-so on.  All functions and structures from each module are imported
-directly into the SDL namespace for convenience.
-
-The extension libraries to SDL must be imported separately if you want
-to use them::
-
-    from SDL.image import *
-    from SDL.mixer import *
-    from SDL.ttf import *
-
-The API documentation lists core functions in both their originating module
-and the SDL module for readability.
-
-Error checking
-==============
-
-Many SDL functions return an error code (the actual code depends on the
-function: some return 0 on error, others return -1 on error).  SDL-ctypes
-hides this detail from the application and will check return codes itself.
-
-When an error code is returned from the SDL library, an ``SDL_Exception``
-is raised.  The message it contains is the return value of ``SDL_GetError``.
-In general this means you can leave out error checking code in your
-application, or use try/except clauses where necessary.
-
-Return by reference
-===================
-
-Some SDL functions return values by storing the result in a pointer
-passed in as a function argument.  Since this convention is unwieldly
-in Python, these functions have been rewritten.  There are three
-types of these functions:
-
- * Those whose return value is an error code.  In this case SDL-ctypes
-   handles the error code itself (raising an exception if necessary),
-   and returns the primary result directly.  An example of this is
-   ``SDL_PollEvent``, which has a C prototype of::
-
-        int SDL_PollEvent(SDL_Event *event);
-
-   This function actually has two behaviours: if ``event`` is NULL the
-   function returns ``SDL_TRUE`` but does not dequeue the event.
-   This is implemented in SDL-ctypes as::
-
-        SDL_PollEvent() -> bool
-
-   If you wish to dequeue and view the event as well, you can use the
-   variant ``SDL_PollEventAndReturn``::
-
-        SDL_PollEventAndReturn() -> SDL_Event
-
- * Those that return multiple values.  An example is ``SDL_GetKeyState``,
-   which has a C prototype of::
-
-        void SDL_GetKeyRepeat(int *delay, int *interval);
-
-   In SDL-ctypes, the two results are returned as a tuple::
-
-        SDL_GetKeyRepeat() -> (delay, interval)
-
- * Those that fill in an array of values.  An example is ``SDL_PeepEvents``,
-   which has a C prototype of::
-
-        int SDL_PeepEvents(SDL_Event *events, int numevents, int action, int
-        mask);
-
-   In SDL-ctypes the array of events is returned as a list::
-
-        SDL_PeepEvents(numevents, action, mask) -> list of SDL_Event
-
-Large arrays
-============
-
-There are times when you need to access and manipulate large arrays
-of data in SDL.  For example, ``SDL_SetGammaRamp`` in C takes
-three arrays of integers.  The ``SDL_Surface.pixels`` attribute in C
-is a void pointer to a large array of pixel data.
-
-In SDL-ctypes the ``SDL_array`` abstraction is used to represent
-large arrays of data, allowing you to choose which format you would
-like the data in.
-
-For example, to access the surface pixels as an instance of ``SDL_array``::
-
-    surface = SDL_SetVideoMode(640, 480, 32, 0)
-    pixels = surface.pixels
-
-``SDL_array`` implements the usual slicing and indexing operators so you
-can access the data element-wise::
-
-    # Set the third pixel to red
-    pixels[3] = SDL_MapRGBColor(surface.format, 255, 0, 0)
-
-    # Set all pixels to white
-    white = SDL_MapRGBColor(surface.format, 255, 255, 255)
-    for i in range(len(pixels)):
-        pixels[i] = white
-
-    # Equivalent to
-    pixels[:] = [white] * len(pixels)
-
-You can also access the data as a NumPy array, if it is installed::
-    
-    pixels = surface.pixels.as_numpy()
-
-The resultant array is mapped directly to the SDL buffer, so updates
-are immediate::
-
-    # Set all pixels to white
-    pixels[:] = [white] * len(pixels)
-
-    # Add one to all pixel values:
-    numpy.add(pixels, 1)
-
-Using NumPy is substantially faster than plain Python code.
-
-If you are using another library that uses ctypes, you can pass it
-the raw buffer as a pointer::
-
-    # Get the ctypes buffer pointer
-    p = surface.pixels.as_ctypes()
-
-So far all demonstrated operations have been on the pixel type; for
-example if using a 32-bit buffer, each element in the array is an
-integer representing the complete buffer.  You can also access the
-raw bytes of the buffer::
-
-    bytes = surface.pixels.as_bytes()
-
-If you know what you're doing, you can manipulate the buffer in the
-same way::
-    
-    # Zero out the third byte of the buffer.
-    bytes[3] = 0 
-
-You can access the byte buffer as a NumPy array or ctypes pointer in
-the same way::
-
-    bytes = surface.pixels.as_bytes().as_numpy()
-    bytes = surface.pixels.as_bytes().as_ctypes()
-
-You have already seen that ``SDL_Surface.pixels`` is an ``SDL_array``.
-Some functions also return ``SDL_array``, which can be manipulated
-in the same way::
-
-    red, green, blue = SDL_GetGammaRamp()
-    red = red.as_numpy()
-    red[:] = numpy.zeros(len(red))
-
-Any sequence, ctypes pointer or NumPy array can be passed as an argument
-to a function expecting ``SDL_array``::
-
-    # red is now a NumPy array; green is still SDL_array; blue is a list
-    SDL_SetGammaRamp(red, green, [0] * 256)
-
-Functions accepting SDL_array also accept any sequence, ctypes pointer
-or NumPy array of a byte buffer::
-
-    SDL_SetGammaRamp(red, green.as_bytes(), [0] * 256 * 2)
-
-SDL_RWops
-=========
-
-``SDL_RWops`` is a structure in SDL that describes a read/write interface
-to an arbitrary object.  For example, the ``SDL_Load_BMP_RW`` function
-can create an ``SDL_Surface`` from any source.
-
-Several functions from SDL have been included in SDL-ctypes for creating
-``SDL_RWops`` from files::
-
-    rw = SDL_RWFromFile('sample.bmp', 'rb')
-
-You can also create an SDL_RWops from any Python file-like object that
-provides read, write, seek and close methods::
-
-    f = open('sample.bmp')
-    rw = SDL_RWFromObject(f)
-
-For example, you could use this functionality to load a bitmap directly
-from a ZIP archive or remote URL.
-
-Version compatibility
-=====================
-
-SDL-ctypes can be used with any SDL shared library from version 2.1.1 
-onwards.  Differences between these versions are handled transparently
-where possible (e.g., the difference in layout between structures).
-
-If you call a function or access a structure member that doesn't exist
-in the version that was linked at runtime, ``SDL_NotImplementedError``
-will be raised.
-
-You can check the version of the runtime library with ``SDL_Linked_Version``.
-
------------------
-Tools and process
------------------
-
-Releasing a snapshot
-====================
-
-1. Increment revision numbers in ``setup.py`` and ``doc/manual.txt``, and
-   ensure ``CHANGELOG`` is up to date.
-2. Update ``doc/index.txt`` and generate ``index.html`` with::
-
-      python setup.py doc
-
-3. Generate user documentation (requires ``mkhowto`` from the Python source
-   and `Python LaTeX Writer
-   <http://www.rexx.com/~dkuhlman/rstpythonlatex_intro.html>`_::
-
-      python setup.py manual
-
-4. Generate API documentation (requires `Epydoc
-   <http://epydoc.sourceforge.net>`_ 3.0 alpha or later)::
-
-      python setup.py apidoc
-
-5. Generate snapshot::
-
-      python setup.py sdist
-
-How API documentation is generated
-==================================
-
-EpyDoc generates HTML pages by both parsing source files and by
-importing the modules and introspecting them.  When EpyDoc is run
-on the SDL package it misses most functions, as they are created
-procedurally with ``SDL.dll.function``.  The parser misses them as
-they look like variable assignments, and the introspector misses them
-as the underlying function is declared in another module.
-
-The script ``support/prep_doc.py`` creates a package in ``build_doc``
-by introspecting the SDL module and writing the function definitions
-and their docstrings in the standard form.  EpyDoc is then run over
-the ``build_doc`` directory to generate useful API documentation.
-
-Run it with::
-
-    python support/prep_doc.py build_doc/
-
-(it is also run automatically by setup.py within the ``apidoc`` commmand.)
-
-Detecting changes in SDL revisions
-==================================
-
-``support/diff_changes.py`` can be used to checkout consecutive releases
-of libsdl and diff each version against its predecessor.  The results
-are written to ``support/diff_1.2.x.txt``, where x is the newer version.
-
-When a new version of SDL is released, add the revision number to
-the script and re-run it.  Examine the generated report for added or
-changed function prototypes and structures, and make the appropriate
-changes to SDL-ctypes.
-
---------------
-Platform Notes
---------------
-
-Linux
-=====
-
-Tested on:
-
-* AMD64 Gentoo; SDL 1.2.11; Python 2.4.2
-
-Mac OS X
-========
-
-You must have PyObjC installed to use the video or surface functions.
-
-Tested on:
-
-* iBook G3 900MHz OS X 1.3.9; SDL 1.2.11 (installed as framework); 
-  Python 2.4.1 (installed from source).
-
-  * CDROM functions do not work (freezes, requires reboot)
-  * SDL_WM_ToggleFullscreen throws an exception with no message.
-
-Windows
-=======
-
-Tested on:
-
-* AMD64 Windows XP (32-bit); SDL 1.2.11 (binaries); Python 2.4.1; Cygwin
-
-  * testgamma raises exception with no message before blanking completely
-    red, leaves entire display with affected gamma.
-  * SDL_WM_ToggleFullscreen throws an exception with no message.
-
+
+:author: Alex Holkner
+:address: aholkner@cs.rmit.edu.au \\\\
+    http://www.pygame.org/ctypes
+
+:revision: 0.05
+:date:  4 July 2006
+
+:copyright: Copyright (c) 2006 Alex Holkner.
+
+==========
+SDL-ctypes
+==========
+
+---------------------
+Introduction
+---------------------
+
+SDL-ctypes is a wrapper module for the `Simple DirectMedia Layer`_ (SDL) and
+its companion libraries SDL_image, SDL_mixer and SDL_ttf.  
+
+Example programs ported from the SDL library are in the ``test`` directory.
+You can use SDL-ctypes to access all SDL functions and data types.
+Pixel and audio buffers can be manipulated using either slices or NumPy_.
+SDL can also provide a context for PyOpenGL_ to work with.
+
+.. _Simple DirectMedia Layer: http://www.libsdl.org
+.. _NumPy: http://numeric.scipy.org
+.. _PyOpenGL: http://pyopengl.sourceforge.net
+
+Versions
+========
+
+SDL-ctypes supports:
+
+    SDL
+        Versions 1.2.1 through 1.2.11
+    SDL_image
+        Unversioned release on 13 April 2002 through 1.2.5
+    SDL_mixer
+        Versions 1.2.6 through 1.2.7
+    SDL_ttf
+        Versions 2.0.7 through 2.0.8
+    SDL_sound   
+        Versions 1.0.0 through 1.0.1
+
+Note that earlier versions are not available through the SDL subversion
+repository.
+
+SDL-ctypes requires Python 2.4 or later.  On Mac OS X SDL-ctypes also requires
+PyObjC to be installed.
+
+---------------------
+Usage
+---------------------
+
+If you are familiar with SDL in C, you should find SDL-ctypes 
+to be fairly intuitive.  The interface has been kept as consistent as
+possible, while making it simple to use in Python.
+
+The following sections detail the general differences you can expect to
+see.
+
+Importing
+=========
+
+The preferred way to use SDL-ctypes is with::
+
+    from SDL import *
+
+This follows the convention of PyOpenGL, and allows you to call SDL
+functions in the same way as the C library.  The actual package is
+composed of several modules such as ``SDL.cdrom``, ``SDL.video``, and
+so on.  All functions and structures from each module are imported
+directly into the SDL namespace for convenience.
+
+The extension libraries to SDL must be imported separately if you want
+to use them::
+
+    from SDL.image import *
+    from SDL.mixer import *
+    from SDL.ttf import *
+
+The API documentation lists core functions in both their originating module
+and the SDL module for readability.
+
+Error checking
+==============
+
+Many SDL functions return an error code (the actual code depends on the
+function: some return 0 on error, others return -1 on error).  SDL-ctypes
+hides this detail from the application and will check return codes itself.
+
+When an error code is returned from the SDL library, an ``SDL_Exception``
+is raised.  The message it contains is the return value of ``SDL_GetError``.
+In general this means you can leave out error checking code in your
+application, or use try/except clauses where necessary.
+
+Return by reference
+===================
+
+Some SDL functions return values by storing the result in a pointer
+passed in as a function argument.  Since this convention is unwieldly
+in Python, these functions have been rewritten.  There are three
+types of these functions:
+
+ * Those whose return value is an error code.  In this case SDL-ctypes
+   handles the error code itself (raising an exception if necessary),
+   and returns the primary result directly.  An example of this is
+   ``SDL_PollEvent``, which has a C prototype of::
+
+        int SDL_PollEvent(SDL_Event *event);
+
+   This function actually has two behaviours: if ``event`` is NULL the
+   function returns ``SDL_TRUE`` but does not dequeue the event.
+   This is implemented in SDL-ctypes as::
+
+        SDL_PollEvent() -> bool
+
+   If you wish to dequeue and view the event as well, you can use the
+   variant ``SDL_PollEventAndReturn``::
+
+        SDL_PollEventAndReturn() -> SDL_Event
+
+ * Those that return multiple values.  An example is ``SDL_GetKeyState``,
+   which has a C prototype of::
+
+        void SDL_GetKeyRepeat(int *delay, int *interval);
+
+   In SDL-ctypes, the two results are returned as a tuple::
+
+        SDL_GetKeyRepeat() -> (delay, interval)
+
+ * Those that fill in an array of values.  An example is ``SDL_PeepEvents``,
+   which has a C prototype of::
+
+        int SDL_PeepEvents(SDL_Event *events, int numevents, int action, int
+        mask);
+
+   In SDL-ctypes the array of events is returned as a list::
+
+        SDL_PeepEvents(numevents, action, mask) -> list of SDL_Event
+
+Large arrays
+============
+
+There are times when you need to access and manipulate large arrays
+of data in SDL.  For example, ``SDL_SetGammaRamp`` in C takes
+three arrays of integers.  The ``SDL_Surface.pixels`` attribute in C
+is a void pointer to a large array of pixel data.
+
+In SDL-ctypes the ``SDL_array`` abstraction is used to represent
+large arrays of data, allowing you to choose which format you would
+like the data in.
+
+For example, to access the surface pixels as an instance of ``SDL_array``::
+
+    surface = SDL_SetVideoMode(640, 480, 32, 0)
+    pixels = surface.pixels
+
+``SDL_array`` implements the usual slicing and indexing operators so you
+can access the data element-wise::
+
+    # Set the third pixel to red
+    pixels[3] = SDL_MapRGBColor(surface.format, 255, 0, 0)
+
+    # Set all pixels to white
+    white = SDL_MapRGBColor(surface.format, 255, 255, 255)
+    for i in range(len(pixels)):
+        pixels[i] = white
+
+    # Equivalent to
+    pixels[:] = [white] * len(pixels)
+
+You can also access the data as a NumPy array, if it is installed::
+    
+    pixels = surface.pixels.as_numpy()
+
+The resultant array is mapped directly to the SDL buffer, so updates
+are immediate::
+
+    # Set all pixels to white
+    pixels[:] = [white] * len(pixels)
+
+    # Add one to all pixel values:
+    numpy.add(pixels, 1)
+
+Using NumPy is substantially faster than plain Python code.
+
+If you are using another library that uses ctypes, you can pass it
+the raw buffer as a pointer::
+
+    # Get the ctypes buffer pointer
+    p = surface.pixels.as_ctypes()
+
+So far all demonstrated operations have been on the pixel type; for
+example if using a 32-bit buffer, each element in the array is an
+integer representing the complete buffer.  You can also access the
+raw bytes of the buffer::
+
+    bytes = surface.pixels.as_bytes()
+
+If you know what you're doing, you can manipulate the buffer in the
+same way::
+    
+    # Zero out the third byte of the buffer.
+    bytes[3] = 0 
+
+You can access the byte buffer as a NumPy array or ctypes pointer in
+the same way::
+
+    bytes = surface.pixels.as_bytes().as_numpy()
+    bytes = surface.pixels.as_bytes().as_ctypes()
+
+You have already seen that ``SDL_Surface.pixels`` is an ``SDL_array``.
+Some functions also return ``SDL_array``, which can be manipulated
+in the same way::
+
+    red, green, blue = SDL_GetGammaRamp()
+    red = red.as_numpy()
+    red[:] = numpy.zeros(len(red))
+
+Any sequence, ctypes pointer or NumPy array can be passed as an argument
+to a function expecting ``SDL_array``::
+
+    # red is now a NumPy array; green is still SDL_array; blue is a list
+    SDL_SetGammaRamp(red, green, [0] * 256)
+
+Functions accepting SDL_array also accept any sequence, ctypes pointer
+or NumPy array of a byte buffer::
+
+    SDL_SetGammaRamp(red, green.as_bytes(), [0] * 256 * 2)
+
+SDL_RWops
+=========
+
+``SDL_RWops`` is a structure in SDL that describes a read/write interface
+to an arbitrary object.  For example, the ``SDL_Load_BMP_RW`` function
+can create an ``SDL_Surface`` from any source.
+
+Several functions from SDL have been included in SDL-ctypes for creating
+``SDL_RWops`` from files::
+
+    rw = SDL_RWFromFile('sample.bmp', 'rb')
+
+You can also create an SDL_RWops from any Python file-like object that
+provides read, write, seek and close methods::
+
+    f = open('sample.bmp')
+    rw = SDL_RWFromObject(f)
+
+For example, you could use this functionality to load a bitmap directly
+from a ZIP archive or remote URL.
+
+Version compatibility
+=====================
+
+SDL-ctypes can be used with any SDL shared library from version 2.1.1 
+onwards.  Differences between these versions are handled transparently
+where possible (e.g., the difference in layout between structures).
+
+If you call a function or access a structure member that doesn't exist
+in the version that was linked at runtime, ``SDL_NotImplementedError``
+will be raised.
+
+You can check the version of the runtime library with ``SDL_Linked_Version``.
+
+-----------------
+Tools and process
+-----------------
+
+Releasing a snapshot
+====================
+
+1. Increment revision numbers in ``setup.py`` and ``doc/manual.txt``, and
+   ensure ``CHANGELOG`` is up to date.
+2. Update ``doc/index.txt`` and generate ``index.html`` with::
+
+      python setup.py doc
+
+3. Generate user documentation (requires ``mkhowto`` from the Python source
+   and `Python LaTeX Writer
+   <http://www.rexx.com/~dkuhlman/rstpythonlatex_intro.html>`_::
+
+      python setup.py manual
+
+4. Generate API documentation (requires `Epydoc
+   <http://epydoc.sourceforge.net>`_ 3.0 alpha or later)::
+
+      python setup.py apidoc
+
+5. Generate snapshot::
+
+      python setup.py sdist
+
+How API documentation is generated
+==================================
+
+EpyDoc generates HTML pages by both parsing source files and by
+importing the modules and introspecting them.  When EpyDoc is run
+on the SDL package it misses most functions, as they are created
+procedurally with ``SDL.dll.function``.  The parser misses them as
+they look like variable assignments, and the introspector misses them
+as the underlying function is declared in another module.
+
+The script ``support/prep_doc.py`` creates a package in ``build_doc``
+by introspecting the SDL module and writing the function definitions
+and their docstrings in the standard form.  EpyDoc is then run over
+the ``build_doc`` directory to generate useful API documentation.
+
+Run it with::
+
+    python support/prep_doc.py build_doc/
+
+(it is also run automatically by setup.py within the ``apidoc`` commmand.)
+
+Detecting changes in SDL revisions
+==================================
+
+``support/diff_changes.py`` can be used to checkout consecutive releases
+of libsdl and diff each version against its predecessor.  The results
+are written to ``support/diff_1.2.x.txt``, where x is the newer version.
+
+When a new version of SDL is released, add the revision number to
+the script and re-run it.  Examine the generated report for added or
+changed function prototypes and structures, and make the appropriate
+changes to SDL-ctypes.
+
+--------------
+Platform Notes
+--------------
+
+Linux
+=====
+
+Tested on:
+
+* AMD64 Gentoo; SDL 1.2.11; Python 2.4.2
+
+Mac OS X
+========
+
+You must have PyObjC installed to use the video or surface functions.
+
+Tested on:
+
+* iBook G3 900MHz OS X 1.3.9; SDL 1.2.11 (installed as framework); 
+  Python 2.4.1 (installed from source).
+
+  * CDROM functions do not work (freezes, requires reboot)
+  * SDL_WM_ToggleFullscreen throws an exception with no message.
+
+Windows
+=======
+
+Tested on:
+
+* AMD64 Windows XP (32-bit); SDL 1.2.11 (binaries); Python 2.4.1; Cygwin
+
+  * testgamma raises exception with no message before blanking completely
+    red, leaves entire display with affected gamma.
+  * SDL_WM_ToggleFullscreen throws an exception with no message.
+
 try: import pygame.mixer
 except (ImportError,IOError), msg:mixer=MissingModule("mixer", msg, 0)
 
-try: import pygame.movie
-except (ImportError,IOError), msg:movie=MissingModule("movie", msg, 0)
+#try: import pygame.movie
+#except (ImportError,IOError), msg:movie=MissingModule("movie", msg, 0)
 
-try: import pygame.movieext
-except (ImportError,IOError), msg:movieext=MissingModule("movieext", msg, 0)
+#try: import pygame.movieext
+#except (ImportError,IOError), msg:movieext=MissingModule("movieext", msg, 0)
 
 try: import pygame.surfarray
 except (ImportError,IOError), msg:surfarray=MissingModule("surfarray", msg, 0)
 try: import pygame.sndarray
 except (ImportError,IOError), msg:sndarray=MissingModule("sndarray", msg, 0)
 
-try: import pygame.fastevent
-except (ImportError,IOError), msg:fastevent=MissingModule("fastevent", msg, 0)
+#try: import pygame.fastevent
+#except (ImportError,IOError), msg:fastevent=MissingModule("fastevent", msg, 0)
 
 #there's also a couple "internal" modules not needed
 #by users, but putting them here helps "dependency finder"
         Note, track 0 is track 1 on the CD.  Track numbers start at zero.
 
         :Parameters:
-            `track`: int
+            `track` : int
                 Track index.
 
         :rtype: float
 ##    Pete Shinners
 ##    pete@shinners.org
 
-"""Set of cursor resources available for use. These cursors come
-in a sequence of values that are needed as the arguments for
-pygame.mouse.set_cursor(). to dereference the sequence in place
-and create the cursor in one step, call like this;
-pygame.mouse.set_cursor(*pygame.cursors.arrow).
+"""Set of cursor resources available for use. 
 
-Here is a list of available cursors; arrow, diamond, ball,
-        broken_x, tri_left, tri_right
+These cursors come in a sequence of values that are needed as the arguments
+for pygame.mouse.set_cursor(). to dereference the sequence in place and create
+the cursor in one step, call like this::
 
-There is also a sample string cursor named 'thickarrow_strings'.
-The compile() function can convert these string cursors into cursor byte data.
+    pygame.mouse.set_cursor(*pygame.cursors.arrow).
+
+Here is a list of available cursors: arrow, diamond, ball, broken_x, tri_left,
+tri_right
+
+There is also a sample string cursor named `thickarrow_strings`.
+The `compile` function can convert these string cursors into cursor byte data.
 """
 
 #default pygame black arrow
         '''Draw text on a new Surface.
 
         This creates a new Surface with the specified text rendered on it.
-        Pygame provides no way to directly draw text on an existing Surface:
+        Pygame provides no way to directly draw text on an existing Surface;
         instead you must use Font.render() to create an image (Surface) of the
         text, then blit this image onto another Surface.
 
         information by colorkey rather than (much less efficient) alpha
         values.
 
-        If you render '\n' a unknown char will be rendered.  Usually a
+        If you render '\\n' a unknown char will be rendered.  Usually a
         rectangle.  Instead you need to handle new lines yourself.
 
         Font rendering is not thread safe: only a single thread can render
     time of the call.
 
     Note, to get all of the mouse events it is better to use either 
-     pygame.event.wait() or pygame.event.get() and check all of those events
+    pygame.event.wait() or pygame.event.get() and check all of those events
     to see if they are MOUSEBUTTONDOWN, MOUSEBUTTONUP, or MOUSEMOTION.
 
     Note, that on X11 some XServers use middle button emulation.  When you click
                 Otherwise, this argument is the depth, specified in bits per
                 pixel.
             `flags` : int  or None
-                  Otherwise, this argument is the flags
-                for the new surface; a combination of SWSURFACE, HWSURFACE
-                or ASYNCBLIT.
+                Otherwise, this argument is the flags for the new surface; a
+                combination of SWSURFACE, HWSURFACE or ASYNCBLIT.
 
         :rtype: `Surface`
         '''
 
 import os, sys
 
+__docformat__ = 'restructuredtext'
+__version__ = '$Id$'
 
 #create simple version of the font name
 def _simplename(name):
 def SysFont(name, size, bold=False, italic=False):
     '''Create a Font object from the system fonts.
 
-    Return a new Font object that is loaded from the system fonts. The font will
-    match the requested bold and italic flags. If a suitable system font is not
-    found this will fallback on loading the default pygame font. The font name
-    can be a comma separated list of font names to look for.
-    
+    Return a new Font object that is loaded from the system fonts. The font
+    will match the requested bold and italic flags. If a suitable system font
+    is not found this will fallback on loading the default pygame font. The
+    font name can be a comma separated list of font names to look for.
+
     :Parameters:
         `name` : str
             Font family or comma-separated list of families.
 
         >>> print pygame.font.match_font('bitstreamverasans')
         '/usr/share/fonts/truetype/ttf-bitstream-vera/Vera.ttf'
-    
+
     :Parameters:
         `name` : str
             Font family or comma-separated list of families.
 __version__ = '$Id:$'
 
 import os
-import os.path
+from os.path import join, abspath, dirname, splitext
 import sys
 import subprocess
 
 from distutils.core import setup
 from distutils.cmd import Command
 
-doc_dir = os.path.join(os.path.abspath(os.path.dirname(sys.argv[0])), 'doc')
-apidoc_dir = os.path.join(doc_dir, 'api')
 
-# customise me:
-latex_writer = \
-    '/usr/lib/python2.4/site-packages/docutils/tools/python_latex.py'
-mkhowto = \
-    '/usr/share/doc/Python-2.5a2/tools/mkhowto'
-rst2html = \
-    'rst2html.py'
+# A "do-everything" command class for building any type of documentation.
+class BuildDocCommand(Command):
+    user_options = [('doc-dir=', None, 'directory to build documentation'),
+                    ('epydoc=', None, 'epydoc executable'),
+                    ('rest-latex=', None, 'ReST LaTeX writer executable'),
+                    ('rest-html=', None, 'ReST HTML writer executable'),
+                    ('mkhowto=', None, 'Python mkhowto executable')]
 
-class ApiDocCommand(Command):
-    description = 'generate HTML API documentation'
+    def initialize_options(self):
+        self.doc_dir = join(abspath(dirname(sys.argv[0])), 'doc')
+        self.epydoc = 'epydoc'
+        self.rest_latex = 'python_latex.py'
+        self.rest_html = 'rst2html.py'
+        self.mkhowto = 'mkhowto'
+
+    def finalize_options(self):
+        pass
+
+    def run(self):
+        if 'pre' in self.doc:
+            subprocess.call(self.doc['pre'], shell=True)
+
+        prev_dir = os.getcwd()
+        if 'chdir' in self.doc:
+            dir = abspath(join(self.doc_dir, self.doc['chdir']))
+            try:
+                os.makedirs(dir)
+            except:
+                pass
+            os.chdir(dir)
+
+        if 'epydoc_packages' in self.doc:
+            cmd = [self.epydoc,
+                   '--no-private',
+                   '--html',
+                   '--no-sourcecode',
+                   '--url=http://www.pygame.org',
+                   '-v']
+            cmd.append('--name="%s"' % self.doc['description'])
+            if 'epydoc_dir' in self.doc:
+                cmd.append('-o %s' % \
+                    abspath(join(self.doc_dir, self.doc['epydoc_dir'])))
+            cmd.append(self.doc['epydoc_packages'])
+            subprocess.call(' '.join(cmd), shell=True)
+
+        if 'rest_howto' in self.doc:
+            txtfile = abspath(join(self.doc_dir, self.doc['rest_howto']))
+            texfile = '%s.tex' % splitext(txtfile)[0]
+            cmd = [self.rest_latex,
+                   txtfile, 
+                   '>',
+                   texfile]
+            subprocess.call(' '.join(cmd), shell=True)
+
+            cmd = [self.mkhowto,
+                   '--split=4',
+                   texfile]
+            subprocess.call(' '.join(cmd), shell=True)
+
+        if 'rest_html' in self.doc:
+            txtfile = abspath(join(self.doc_dir, self.doc['rest_html']))
+            htmlfile = '%s.html' % splitext(txtfile)[0]
+            cmd = [self.rest_html,
+                   txtfile,
+                   '>',
+                   htmlfile]
+            subprocess.call(' '.join(cmd), shell=True)
+
+        os.chdir(prev_dir)
+
+# Fudge a command class given a dictionary description
+def make_doc_command(**kwargs):
+    class c(BuildDocCommand):
+        doc = dict(**kwargs)
+        description = 'build %s' % doc['description']
+    c.__name__ = 'build_doc_%s' % c.doc['name'].replace('-', '_')
+    return c
+
+# This command does nothing but run all the other doc commands.
+# (sub_commands are set later)
+class BuildAllDocCommand(Command):
+    description = 'build all documentation'
     user_options = []
+    sub_commands = []
 
     def initialize_options(self):
         pass
         pass
 
     def run(self):
-        subprocess.call('python support/prep_doc.py build_doc/',
-                        shell=True)
-        try:
-            os.makedirs(apidoc_dir)
-        except:
-            pass
-        olddir = os.getcwd()
-        os.chdir('build_doc')
-        subprocess.call('epydoc --no-private --html --no-sourcecode ' + \
-                        '--name=SDL-ctypes --url=http://www.pygame.org ' + \
-                        '-v -o %s SDL' % apidoc_dir,
-                        shell=True)
-        os.chdir(olddir)
+        for cmd_name in self.get_sub_commands():
+            self.run_command(cmd_name)
 
-class ManualDocCommand(Command):
-    description = 'generate HTML manual documentation'
-    user_options = []
+extra_cmds = {
+    'build_doc_sdl_api': make_doc_command(
+         name='sdl-api',
+         description='SDL-ctypes API documentation',
+         chdir='.build-sdl-doc',
+         pre='python support/prep_doc.py doc/.build-sdl-doc',
+         epydoc_dir='sdl-api',
+         epydoc_packages='SDL'),
+    'build_doc_pygame_api': make_doc_command(
+         name='pygame-api',
+         description='Pygame-ctypes API',
+         epydoc_dir='pygame-api',
+         epydoc_packages='pygame'),
+    'build_doc_sdl_manual': make_doc_command(
+         name='sdl-manual',
+         description='SDL-ctypes manual',
+         chdir='',
+         rest_howto='sdl-manual.txt'),
+    'build_doc_index': make_doc_command(
+         name='index',
+         description='documentation index',
+         chdir='',
+         rest_html='index.txt'),
+    'build_doc': BuildAllDocCommand
+}
 
-    def initialize_options(self):
-        pass
-
-    def finalize_options(self):
-        pass
-
-    def run(self):
-        olddir = os.getcwd()
-        os.chdir(doc_dir)
-        subprocess.call('%s manual.txt > manual.tex' % latex_writer, shell=True)
-        subprocess.call('%s --split=4 manual.tex' % mkhowto, shell=True)
-        os.chdir(olddir)
-
-class DocCommand(Command):
-    description = 'generate HTML index page'
-    user_options = []
-
-    def initialize_options(self):
-        pass
-
-    def finalize_options(self):
-        pass
-
-    def run(self):
-        olddir = os.getcwd()
-        os.chdir(doc_dir)
-        subprocess.call('%s index.txt > index.html' % rst2html, shell=True)
-        os.chdir(olddir)
+for name in extra_cmds.keys():
+    if name != 'build_doc':
+        BuildAllDocCommand.sub_commands.append((name, None))
 
 setup(
-    name='SDL-ctypes',
+    name='pygame-ctypes',
     version='0.05',
-    description='ctypes wrapper for SDL',
+    description='Python game and multimedia package',
     author='Alex Holkner',
     author_email='aholkner@cs.rmit.edu.au',
     url='http://www.pygame.org/ctypes',
     license='LGPL',
-    cmdclass={'apidoc':ApiDocCommand, 
-              'manual':ManualDocCommand,
-              'doc':DocCommand},
-    packages=['SDL'],
+    cmdclass=extra_cmds,
+    packages=['SDL', 'pygame'],
 )
 
     write_module(SDL.mixer)
     write_module(SDL.image)
     write_module(SDL.sound)
+
+    # Keep epydoc from crashing trying to import this outside mac
+    #open(os.path.join(base_dir, 'SDL/darwin.py'), 'w').write(\
+    #    "'''Darwin (OS X) support.\n\nInternal use only.'''\n\n" \
+    #    "def init():\n pass\n")
+