Major docs overhaul

After experience at several picademies I've got a better handle on
what's needed in the docs. There's no point forcing "with" down
everyone's throat - it's just another thing to learn up front which
isn't strictly necessary so it's gone from all basic recipes (the
advanced recipes keep it though).

The quickstart chapter is pointless - everyone goes straight to recipes.
Better to replace it with a nice illustrated guide to camera module
installation.

The private methods in PiCamera are better off out of the documentation.
The only people using these are more than capable of reading the
docstrings in the class (which are still there) and simplifying the API
docs might just get a few more people reading them (they're largely
ignored at the moment).

Finally, to make the TOC less daunting only top-level chapters are
included.

docs/api_array.rst

@@ -1,8 +1,77 @@
 .. _api_array:
 
-===============================
-API - ``picamera.array`` Module
-===============================
+============
+API - Arrays
+============
 
-.. automodule:: picamera.array
+.. module:: picamera.array
+
+.. currentmodule:: picamera.array
+
+The picamera library provides a set of classes designed to aid in construction
+of n-dimensional `numpy`_ arrays from camera output. In order to avoid adding a
+hard dependency on numpy to picamera, this module (:mod:`picamera.array`) is
+not automatically imported by the main picamera package and must be explicitly
+imported, e.g.::
+
+    import picamera
+    import picamera.array
+
+.. _numpy: http://www.numpy.org/
+
+
+PiArrayOutput
+=============
+
+.. autoclass:: PiArrayOutput
+    :members:
+
+
+PiRGBArray
+==========
+
+.. autoclass:: PiRGBArray
+
+
+PiYUVArray
+==========
+
+.. autoclass:: PiYUVArray
+
+
+PiBayerArray
+============
+
+.. autoclass:: PiBayerArray
+
+
+PiMotionArray
+=============
+
+.. autoclass:: PiMotionArray
+
+
+PiAnalysisOutput
+================
+
+.. autoclass:: PiAnalysisOutput
+    :members:
+
+
+PiRGBAnalysis
+=============
+
+.. autoclass:: PiRGBAnalysis
+
+
+PiYUVAnalysis
+=============
+
+.. autoclass:: PiYUVAnalysis
+
+
+PiMotionAnalysis
+================
+
+.. autoclass:: PiMotionAnalysis
 

docs/api_camera.rst

@@ -1,8 +1,37 @@
 .. _api_camera:
 
-================================
-API - ``picamera.camera`` Module
-================================
+========================
+API - The PiCamera Class
+========================
 
-.. automodule:: picamera.camera
+.. module:: picamera
+
+The picamera library contains numerous classes, but the primary one that all
+users are likely to interact with is :class:`PiCamera`, documented below.
+With the exception of the contents of the :mod:`picamera.array` module, all
+classes in picamera are accessible from the package's top level namespace.
+In other words, the following import is sufficient to import everything in
+the library (excepting the contents of :mod:`picamera.array`)::
+
+    import picamera
+
+PiCamera
+========
+
+.. autoclass:: PiCamera
+    :members:
+
+
+PiVideoFrameType
+================
+
+.. autoclass:: PiVideoFrameType
+    :members:
+
+
+PiVideoFrame
+============
+
+.. autoclass:: PiVideoFrame(index, frame_type, frame_size, video_size, split_size, timestamp)
+    :members:
 

docs/api_color.rst

@@ -1,8 +1,62 @@
 .. _api_color:
 
 ===============================
-API - ``picamera.color`` Module
+API - Colors and Color Matching
 ===============================
 
-.. automodule:: picamera.color
+.. currentmodule:: picamera
+
+The picamera library includes a comprehensive :class:`Color` class which
+is capable of converting between numerous color representations and calculating
+color differences. Various ancillary classes can be used to manipulate aspects
+of a color.
+
+
+Color
+=====
+
+.. autoclass:: Color
+    :members:
+
+
+Red
+===
+
+.. autoclass:: Red
+    :members:
+
+
+Green
+=====
+
+.. autoclass:: Green
+    :members:
+
+
+Blue
+====
+
+.. autoclass:: Blue
+    :members:
+
+
+Hue
+===
+
+.. autoclass:: Hue
+    :members:
+
+
+Saturation
+==========
+
+.. autoclass:: Saturation
+    :members:
+
+
+Lightness
+=========
+
+.. autoclass:: Lightness
+    :members:
 

docs/api_encoders.rst

@@ -1,8 +1,117 @@
 .. _api_encoders:
 
-==================================
-API - ``picamera.encoders`` Module
-==================================
+==============
+API - Encoders
+==============
 
-.. automodule:: picamera.encoders
+.. currentmodule:: picamera
+
+Encoders are typically used by the camera to compress captured images or video
+frames for output to disk. However, picamera also has classes representing
+"unencoded" output (raw RGB, etc). Most users will have no direct need to use
+these classes directly, but advanced users may find them useful as base classes
+for :ref:`custom_encoders`.
+
+PiEncoder
+=========
+
+.. autoclass:: PiEncoder
+    :members:
+    :private-members:
+
+
+PiVideoEncoder
+==============
+
+.. autoclass:: PiVideoEncoder
+    :members:
+    :private-members:
+
+
+PiImageEncoder
+==============
+
+.. autoclass:: PiImageEncoder
+    :members:
+    :private-members:
+
+
+PiRawMixin
+==========
+
+.. autoclass:: PiRawMixin
+    :members:
+    :private-members:
+
+
+PiCookedVideoEncoder
+====================
+
+.. autoclass:: PiCookedVideoEncoder
+    :members:
+    :private-members:
+
+
+PiRawVideoEncoder
+=================
+
+.. autoclass:: PiRawVideoEncoder
+    :members:
+    :private-members:
+
+
+PiOneImageEncoder
+=================
+
+.. autoclass:: PiOneImageEncoder
+    :members:
+    :private-members:
+
+
+PiMultiImageEncoder
+===================
+
+.. autoclass:: PiMultiImageEncoder
+    :members:
+    :private-members:
+
+
+PiRawImageMixin
+===============
+
+.. autoclass:: PiRawImageMixin
+    :members:
+    :private-members:
+
+
+PiCookedOneImageEncoder
+=======================
+
+.. autoclass:: PiCookedOneImageEncoder
+    :members:
+    :private-members:
+
+
+PiRawOneImageEncoder
+====================
+
+.. autoclass:: PiRawOneImageEncoder
+    :members:
+    :private-members:
+
+
+PiCookedMultiImageEncoder
+=========================
+
+.. autoclass:: PiCookedMultiImageEncoder
+    :members:
+    :private-members:
+
+
+PiRawMultiImageEncoder
+======================
+
+.. autoclass:: PiRawMultiImageEncoder
+    :members:
+    :private-members:
 

docs/api_exc.rst

@@ -1,8 +1,60 @@
 .. _api_exc:
 
-=============================
-API - ``picamera.exc`` Module
-=============================
+================
+API - Exceptions
+================
 
-.. automodule:: picamera.exc
+.. currentmodule:: picamera
+
+All exceptions defined by picamera are listed in this section. All exception
+classes utilize multiple inheritance in order to make testing for exception
+types more intuitive. For example, :exc:`PiCameraValueError` derives from both
+:exc:`PiCameraError` and :exc:`ValueError`. Hence it will be caught by blocks
+intended to catch any error specific to the picamera library::
+
+    try:
+        camera.brightness = int(some_user_value)
+    except PiCameraError:
+        print('Something went wrong with the camera')
+
+Or by blocks intended to catch value errors::
+
+    try:
+        camera.contrast = int(some_user_value)
+    except ValueError:
+        print('Invalid value')
+
+
+Warnings
+========
+
+.. autoexception:: PiCameraWarning
+
+.. autoexception:: PiCameraDeprecated
+
+.. autoexception:: PiCameraFallback
+
+
+Exceptions
+==========
+
+.. autoexception:: PiCameraError
+
+.. autoexception:: PiCameraValueError
+
+.. autoexception:: PiCameraRuntimeError
+
+.. autoexception:: PiCameraClosed
+
+.. autoexception:: PiCameraNotRecording
+
+.. autoexception:: PiCameraAlreadyRecording
+
+.. autoexception:: PiCameraMMALError
+
+
+Functions
+=========
+
+.. autofunction:: mmal_check