Rewrite and categorize the main sdl2.ext docs (#209)

* Major reorganization of the ext docs index

* Minor cleanup

* Add uisystem deprecation notices to news

Author: a-hurst

doc/modules/ext/particles.rst

@@ -1,8 +1,8 @@
 .. module:: sdl2.ext.particles
    :synopsis: A simple particle system.
 
-sdl2.ext.particles - A simple particle system
-=============================================
+A simple particle system
+========================
 
 .. class:: ParticleEngine()
 

doc/modules/ext/sprite.rst doc/modules/ext/spritesystem.rstdoc/modules/ext/sprite.rst renamed to doc/modules/ext/spritesystem.rst

@@ -1,7 +1,11 @@
 .. currentmodule:: sdl2.ext
 
-User interface elements
-=======================
+Designing component-oriented user interfaces
+============================================
+
+.. warning::
+   This module is deprecated, and may be removed in a future release of PySDL2.
+
 User interface elements within :mod:`sdl2.ext` are simple
 :class:`Sprite` objects, which are enhanced by certain input hooks; as such,
 they are not classes on their own, but implemented as mixins. The user input
@@ -17,6 +21,7 @@ elements, which support the event type.
 
 .. _ui-elem-types:
 
+
 UI element types
 ----------------
 Every :class:`sdl2.ext` UI element is a simple :class:`Sprite` object, to

doc/modules/ext/uisystem.rst

@@ -1,17 +1,111 @@
 .. module:: sdl2.ext
-   :synopsis: Python extensions for SDL2
+   :synopsis: Helpful wrappers for the SDL2 API
 
-sdl2.ext - Python extensions for SDL2
-=====================================
-The :mod:`sdl2.ext` package provides advanced functionality for creating
-applications using SDL2 and Python. It offers a rich set of modules, classes
-and functions, such as easy image loading, basic user interface elements,
-resource management and sprite and (on-screen) scene systems. 
+sdl2.ext - Helpful wrappers for the SDL2 API
+============================================
 
-Learn more about
+The :mod:`sdl2.ext` module provides a rich set of modules, classes, and
+functions for creating games and other applications using PySDL2.
+
+The aim of the `sdl2.ext` module is to wrap commonly-used parts of the SDL2 API
+in a more friendly and Pythonic manner, reducing the need for developers to
+understand the intricacies of working with ``ctypes`` and making it simpler and
+more fun to get PySDL2 programs up and running.
+
+In addition, this module provides a number of template classes and utility
+functions for working with colors, input events, file assets, and more.
+
+Due to its broad scope, the :mod:`sdl2.ext` module is divided into a number of
+submodules. However, everything in these submodules can be imported directly
+from :mod:`sdl2.ext`. For example, ``from sdl2.ext import Window`` is exactly
+the same as ``from sdl2.ext.window import Window``.
+
+
+SDL2 module wrappers
+--------------------
+
+Some parts of the :mod:`sdl2.ext` module contain Pythonic wrappers for common
+and/or unpleasant parts of the SDL2 API. At present, these modules include:
+
+.. toctree::
+	:maxdepth: 1
+
+	ext/common.rst
+	ext/window.rst
+	ext/renderer.rst
+	ext/msgbox.rst
+
+
+Utilities for working with SDL2 in Python
+-----------------------------------------
+
+Other parts of this module implement functions and classes that make it easier
+to work with SDL2 functions and data structures in Python (and vice versa).
+These include functions for converting text to and from UTF8-encoded bytes,
+reading and writing ``ctypes`` arrays, and casting :obj:`~sdl2.SDL_Surface`
+objects to Numpy arrays:
+
+.. toctree::
+	:maxdepth: 1
+
+	ext/compat.rst
+	ext/array.rst
+	ext/pixelaccess.rst
+
+
+SDL2-based extensions
+---------------------
+
+In addition to simple Pythonic wrappers for SDL2 functions and structures, the
+:mod:`sdl2.ext` module also offers a number of  high-level classes and functions
+that use SDL2 internally to provide APIs for font rendering, building GUIs,
+importing images, and more:
+
+.. toctree::
+	:maxdepth: 1
+
+	ext/surface.rst
+	ext/draw.rst
+	ext/image.rst
+	ext/ttf.rst
+	ext/bitmapfont.rst
+
+
+Useful helpers for building apps
+--------------------------------
+
+Beyond wrappers and utilities for working with SDL2's API, the
+:mod:`sdl2.ext` module also includes a number of submodules with various
+functions and classes to help facilitate general game and app development with
+PySDL2. These include classes for managing program resource files, working
+with colors, and more:
+
+.. toctree::
+	:maxdepth: 1
+
+	ext/resources.rst
+	ext/color.rst
+	ext/colorpalettes.rst
+	ext/algorithms.rst
+
+
+Component-Oriented Systems
+--------------------------
+
+PySDL2 contains several modules designed around the concept of
+component-oriented game programming. These modules define various types of
+"systems" for processing events and "factories" for creating different types
+of objects, among other things.
+
+.. note::
+   These modules are not regularly maintained, and their documentation
+   may be inaccurate or out-of-date.
 
 .. toctree::
 	:maxdepth: 1
-	:glob:
 
-	ext/*
+	ext/ebs.rst
+	ext/events.rst
+	ext/spritesystem.rst
+	ext/uisystem.rst
+	ext/particles.rst

doc/modules/sdl2ext.rst

@@ -131,6 +131,10 @@ Deprecation Notices:
   :meth:`sdl2.ext.BitmapFont.render_text`, which returns an SDL surface instead
   of a SoftwareSprite and ensures the output surface is in ARGB8888 format by
   default (PR #208)
+* The :class:`~sdl2.ext.UIFactory` and :class:`~sdl2.ext.UIProcessor` classes
+  have been deprecated due to their complexity and maintenance burden. New
+  functions and classes for creating GUIs with PySDL2 may be introduced in a
+  future release (PR #209)
 
 
 0.9.9

doc/news.rst

@@ -79,8 +79,7 @@ class MPEventHandler(EventHandler):
     """
     def __init__(self, sender, maxprocs=None):
         if not _HASMP:
-            raise UnsupportedError(MPEventHandler,
-                                   "no multiprocessing support found")
+            raise UnsupportedError("no multiprocessing support found")
         super(MPEventHandler, self).__init__(sender)
         self.maxprocs = maxprocs